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About the Documentation Set 


The ASM68K. documentation set includes three manuals: 


1. The Reference Manual contains complete descriptions for the assembler 
syntax and directives, linker commands, and librarian commands. Sample 
program listings are used as examples for the assembler, linker, and object 
module librarian. Error and warning messages are described. 


2. The User's Guide contains host computer and operating system-specific 
syntax for invoking the assembler, linker, and object module librarian. 


3. The Installation Guide contains host computer and operating system- 
specific directions for installing the ASM68K package. 


About this Manual 


| 
| ( \ The ASM68K Reference Manual is written for the experienced program developer 
t and assumes a working knowledge of the 68000/10/20/30/40 and CPU32 family of 
microprocessors and the 68881/82 and 68851 coprocessors. 


This manual describes the assembler, linker, and object module librarian. It 
contains the following chapters and appendices: 


e Chapter 1 contains an introduction to the ASM68K software package. 
Key features of the ASM68K software as well as an overview are 
provided. 


e Chapters 2 through 9 describe the ASM68K Assembler syntax and 

directives, and include several useful and informative program 

| examples. Relocation, addressing modes, macros, and structured control 
statements are also explained in these chapters. 


¢ Chapters 10 through 12 describe the LNK68K Linker used to produce 
absolute object modules. Concepts and commands, useful program 
examples for linking relocatable object modules from the assembler or 
librarian, and incremental linking are described in these chapters. 


| e Chapters 13 through 15 describe the LIB68K Object Module Librarian 
used to combine relocatable object modules into a library. Concepts and 
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commands.as well as useful examples of the librarian are provided in 
these chapters. 


* Appendix A contains hexadecimal values of ASCII and EBCDIC 
characters. 


¢ Appendices B through D contain warning and error messages for the 
assembler, linker, and librarian. 


e Appendix E contains a glossary of commonly-used terms. 


« Appendix F describes how the assembler, linker, and librarian were 
modified to support C++. 


¢ Appendix G describes object module records. 


¢ Appendix H contains information on commands that will not be 
supported in the next software release. 


This manual does not describe the 68000 series of microprocessors nor does it help 
you to write working programs. For such information, refer to the following 
sources: 


1. 


The Motorola M68000 Resident Structured Assembler Reference Manual, 
M68KMASM/D8 


. Motorola 68000 Microprocessor User's Manual, M68000UM(AD4) 


3. Motorola 68020 Microprocessor User’ s Manual, MC68020UM/AD REV 1 
4. Motorola MC68881/MC68882_ Floating-Point Coprocessor User's 


Manual, MC68881UM/AD REV 1 


. Motorola 68030 Enhanced 32-Bit Microprocessor User’s Manual, 


MC68030UM/AD 


. MC68040 Enhanced 32-Bit Third Generation Microprocessor User's 


Manual, MC68040UM/AD 


- Motorola 68851 Paged Memory Management Unit User's Manual, 


MC68851UM/AD 


. Motorola CPU Central Processor Unit Reference Manual, CPU32RM/AD 
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Notational Conventions 


The Microtec Research ASM68K Reference Manual uses the following conventions 
shown in Table P-1 (unless otherwise noted). 


Table P-1. Notatlonal Conventions for the Reference Manual 


Symbol Name 


Curly Braces Encloses a required argument. 


Curly Braces Encloses an item that appears 
with Ellipsis 1 or more times. 


Square Brackets Encloses an item that appears 
0 or 1 time. 


Square Brackets Encloses an item that appears 


with Ellipsis 0 or more times. 
F Vertical Bar Separates alternative items in a 
C list, 


= italics Indicates a descriptive item that 
should be replaced with an actual 
item. 


Questions and Suggestions 


To help us respond to questions or suggestions regarding the ASM68K assembler 
package, we have provided two response forms in the back of this manual. 


The first form is a Reader’s Response sheet, which is used to help us correct and 
improve our documentation, We always appreciate your comments, and by 
completing this form, you can participate directly in the revisions of future 
publications. The Reader’s Response sheet is directed to Technical Publications. 


The second form is a Software Performance Report which should be completed if 
you encounter any errors or problems with Microtec Research software. This report 
is directed to Technical Support. 
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Introduction 1 


Overview of the ASM68K Software Package 


The Microtec Research ASM68K Relocatable Macro Assembler for the 68000 
family of microprocessors translates symbolic machine instructions into binary 
object code that can be executed by a 68000 family microprocessor. The 68000 
family includes the 68000, 68008, 68010, 68012, CPU32, 68020, 68030, and 68040 
microprocessors. The instructions specific to the 68881/68882 and 68851 are also 
translated into binary code for coprocessor execution. 


The ASM68K package consists of an assembler, a linker, and an object module 
librarian: 


«© The ASM68K Assembler is a two-pass program that issues helpful error 
messages, produces an easy-to-read program listing and symbol table, 
and generates a computer-readable absolute or relocatable object (link) 
module. 


The assembler produces object code in a relocatable format. Multiple 
relocatable modules are then typically linked into a single absolute 
module by the LNK68K Linker. 


¢ The LNK68K Linker produces an output object module file in standard 
Motorola S-Record format, IEEE-695 object format suitable for XRAY 
input, or HP 64000 OMF for emulation on Hewlett Packard 64000 series 
emulators. Both global and local symbols may be included in the output 
object module file for symbolic debugging with the Microtec Research 
XRAY68K Debugger. 


The linker also contains an incremental linking feature. LNK68K can 
combine multiple relocatable object modules into a single relocatable 
object module suitable for relinking with other modules. 


« The LIB68K Librarian can group relocatable object modules in 
libraries. The library modules can then be linked with other relocatable 
modules using LNK68K. Only those library modules required to resolve 
external references will be linked into the final object module. 


The ASM68K mnemonic operation codes, the assembler directives, and the 
assembler syntax are compatible with that used by Motorola in its software products 
and documentation. 
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Introduction 


Either the 68000, 68010, CPU32, 68020, 68030, or 68040 instruction set can be OG 
selected. The assembler will check that only the appropriate instructions are used 
for the selected processor. 


ASM68K Features 


Significant features of ASM68K include: 


e 


68000/10/20/30/40 and CPU32 instructions supported 
6888 1/82 floating-point instructions 

68851 paged MMU instructions 

Versatile directive set 

Address constants can be easily specified 
Assembly-time relative addressing 

Several different data creation statements 

Storage reservation statements 

Character codes can be specified in ASCII or EBCDIC 
Flexible assembly listing contro! statements 
Comments and remarks can be used for documentation 
Manufacturer-compatible symbolic machine operation codes (opcodes, 


sivectiven) 2 
Symbolic and relative address assignments and references ) 
Symbol or cross-reference table listings 
Absolute object modules can be produced in Motorola S-Record, 
IEEE-695, or HP-OMF format 
Absolute or relocatable (incremental linking) object modules generated 
by the linker 
Complex expression evaluation 
Unlimited forward symbolic references 
Conditional assembly facility 
User-defined macro facility 
Run-time structured loop control directives 
Symbols in the output object module for symbolic debugging 
Complex relocation in the linker 
High-level debugging information for the Microtec Research 
XRAY68K Debugger 


Symbols can be made case-sensitive or case-insensitive 
C++ support 


These features will help you to produce well-documented, modular, working 


programs, 


es 


UO 
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Assembly Language 2 


Introduction 


A 68000/10/20/30/40 and CPU32 microprocessor executable program consists of a 
sequence of 8-bit binary numbers contained in memory. These numbers represent 
68000/10/20/30/40 and CPU32 instructions, memory addresses, and data. It is 
possible to program the 68000/10/20/30/40 and CPU32 by manually calculating 
and encoding the numbers that cause the microprocessor to perform the desired 
functions. However, this method is very slow and tedious. An assembler provides 
an easier method of writing programs by allowing machine instructions to be 
encoded symbolically with English-like mnemonics and symbols. 


This chapter describes the format of assembly language source files and the 
statements that comprise them. 


Assembler Statements 


An assembly language progtam is comprised of statements written in symbolic 
machine language. There are four types of assembly language statements: 


¢ Instruction statements 
¢ Directive statements 

¢ Macro statements 

e¢ Comment statements 


The syntax for instructions, directives, and macros is shown below: 
Syntax: 
label operation operand comment 
Description: 
The components of an assembler statement are defined below. 


label The label field assigns a memory address or constant value 
to the symbolic name contained in the field. The label field 
may begin in any column if terminated by a colon, or it must 
begin in column one when the colon is omitted. A label can 
be the only field in a statement. 


The first 127 characters of a label are significant. 
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Labels are case-sensitive by default. Case-insensitivity can 
be tured on by using the OPT NOCASE assembler 
directive. 

operation The operation field specifies a symbolic operation code, a 
directive, or a macro call. If present, this field must either 
begin after column one or be separated from the label field 
by one or more blanks, tabs, or a colon. 


operand The operand field is used to enter arguments for the opcode, 
directive, or macro specified in the operation field. The 
operand field, if present, is separated from the operation field 
by one or more blanks or tabs. 


comment The comment field provides a place to put a message stating 
the purpose of a statement or group of statements. The 
comment field is always optional and, if present, must be 
separated from the preceding field by one or more blanks, 
tabs, an exclamation point, or a semicolon. For those 
opcodes and directives having optional operands that are not 
present, the comment field must always start with an 
exclamation point or a semicolon. 


The various fields that comprise a statement are separated by one or more blanks or 
tabs and, in some cases, a colon or semicolon. Statements can be a maximum of 512 
characters long. 

Statement Examples 


The following sections show examples of the types of assembly statements 


Instruction Statement 


The symbolic machine instruction is a written specification for a particular machine 
operation, expressed by a symbolic operation code, also called a mnemonic, and 
operands. Symbolic addresses can be defined by the statement as well as used for 
opcode operands. 


Example: 


ISAM MOVE MEM,D2 


where: 
ISAM Is a symbol (/abel) representing the memory address of the 
instruction. 
MOVE Is a symbolic opcode (operation) representing the bit pattern 
of the load instruction. 
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= MEM Isa symbol (operand) representing a memory address. 
D2 Is a reserved symbol (part of operand) representing data 
tegister number 2. 
Directive Statement 


A directive statement is interpreted as a control statement to the assembler. It is not 
translated into a machine instruction. 


Example: 
ABAT DC DELT 
where: 


ABAT Is a symbol (/abel). The assembler will assign the value of 
the current assembly program counter to this symbol. The 
assembly program counter contains the address of the first 
byte of the code generated by the directive pc. 


pe ° Is a directive (operation) that instructs the assembler 
program to allocate two bytes of memory. 


DELT Is asymbol (operand) representing an address. The address 
‘ae. will be placed into the two bytes allocated by the nc 
cee directive, 
Macro Statement 


A macro statement is a call to a sequence of instructions. The call can be made 
many times from any part of the program. The requirements for creating macros 
are described in the chapter, Macros. The macro call has the same format as a 
directive statement, except that the operator is one of the macro commands. 


Example: 


M1 MACRO X,Y 


where: 
M1 Is the name used to call the macro from other parts of the 
program, 
MACRO - Is a directive that assigns a name and a formal set of 


parameters to the operands in the statement. This directive 
also indicates that all of the statements following statements, 
up to the occurrence of the ENDM directive, are part of the 
macro definition. 


a 
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x; ¥ Are symbols that represent parameters that are passed to the 
macro. 


Comment Statement 


A comment statement is not processed by the assembler. Instead, it is reproduced 
on the assembly listing and can be used to document groups of assembly language 
statements. A comment statement is indicated by an asterisk, exclamation point, or 
semicolon as the first nonblank character on a line. 


Example: 
® This is a comment statement. 


! This is another comment statement. 
+ This is another comment statement. 


Blank lines are also treated as comment statements. 


Note 


An asterisk is considered a comment statement only if it is in the 


first column. In any other column, the asterisk may be interpreted 
as the assembly program counter or multiplication operator. 
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Symbolic Addressing 


When writing statements in assembler language, the machine operation code is 
usually expressed symbolically. For example, the machine instruction that rotates 
the contents of Data Register 1 to the left one bit can be expressed as: 


ROL #1,D1 
When translating this symbolic operation code and its arguments into machine code 
for the 68000, the assembler defines two bytes containing $E3 and $59 at the 
memory location indicated by the current assembly program counter. The assembly 
program counter is an internal variable kept by the assembler that is always set to 
the address of the byte currently being assembled. 


You may optionally attach a label to such an instruction. 
Example: 
SAVR ROL #1,D1 ; SAVR is a label 


Whenever there is a valid symbol in the label field, the assembler assigns the 
address contained in the assembly program counter to the symbol. In the given 
example, if the Roz instruction is to be stored at the address 127, then the symbol 
SAVR will be set to the value 127 for the duration of the assembly. 


The symbol could then be used anywhere in the source program to refer to the 
instruction location. The important concept is that the address of the instruction 
need not be known; only the symbol need be used to refer to the instruction location. - 


Therefore, when jumping to the RoL instruction, you could write: 
UMP SAVR 


When the jump instruction is translated into machine code by the assembler, the 
address of the Rox instruction is placed in the address field of the instruction. 


Assembly-Time Relative Addressing 


Symbolic addresses can be used to refer to nearby locations without defining new 
labels. This form of addressing is called relative addressing and may be 
accomplished through the use of the plus (+) and minus (-) operators. 


Example: 

PTAB EQU $F37 
JMP BEG+6 

BEG MOVE D1,D2 
CMPI.B #S2F, (A3) 
ROL #2,D1 
ADDQ €7,PTAB 

END 
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In this example, the instruction ump BEG+6 refers to the ROL instruction, BEG+6 
means the address of BEG plus 6 bytes. 


This type of addressing is not recommended as the variation in the number of bytes 
per instruction will tend to cause references to the wrong location. In the above 
example, for instance, the Move instruction requires 2 bytes and the cmP1 instruction 
requires 4 bytes. , 


The expansion of the above example is shown as follows: 


00000F37 PTAB EQU $¥F37 

00000000 4EFA 000A 4E71 JMP BEG+6 

00000006 3401 BEG MOVE D1,D2 

00000008 0C13 002F CMPI.B #$2F, (A3) 

0000000C E5539 ROL #2,D1 

COCOCOOE S5E78 OF37 ADDO #7,PTAB 
END 


The assembler language, like other programming languages, has a character set, a 
vocabulary, rules of grammar, and allows for the definition of new words or 
elements. The rules that describe the language are referred to as the “‘syntax’’ of the 


language. 


Character Set 


The assembler recognizes the alphabetical characters A-Z and a-z, the numeric 
characters 0-9, and the special characters shown in Table 2-1. Any other characters, 
except those in a comment field or a string, generate an error. Many of the special 
characters have no previously-defined meanings except as character constants. 


The characters are not case-sensitive by default. If case-sensitivity is turned on, the 
case is maintained. ; 


Table 2-1. Special Characters Recognized by the Assembier 


ampersand exclamation tight brace 
asterisk greater than tight bracket 

at sign left brace tight parenthesis 
back quote (accent grave) left bracket ; semicolon 

back slash left parenthesis sharp 

blank single quote 


colon i i slash 

comma i tab 

dollar F i tilde 

double quote i underscore 

equal sign question mark uparrow (caret) 
vertical bar 
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Symbols 


A symbol is a sequence of characters. The first character in a symbol must be 
alphabetic or one of three special characters: 


1. ? question mark 


2. . ~~ period 

3. _ underscore 
Symbols can be up to 127 characters in length; the first 127 characters are 
significant. Subsequent characters in the symbol can consist of any of the special 
characters just mentioned, a dollar sign ($), alphabetic letters, or numeric digits. 
Embedded blanks are not permitted in symbols. Symbols can be made case- 
insensitive by using the OPT NOCASE directive. 


The assembler treats symbols beginning with two or more question marks (¢.g., 

??LAB1) as assembler-generated symbols. When the assembler creates unique 

labels in macro expansions, it generates symbols in the form ??0001, ?70002, and 

so on. These assembler-generated symbols are not included in the assembler listing 

or in the HP asmb_sym file unless the OPT G assembler flag is set. If you do code 

your own symbols beginning with two question marks, these symbols are not 
C available for debugging unless you specify the OPT G directive. 


The assembler generates local symbols in macros that start with the character 
sequence \@. These symbols are only valid inside a macro. 


Symbols are used to represent arithmetic values, memory addresses, bit arrays 
(masks), etc. 


Examples of valid symbols: 


LAB1 

mask 

LOOP SNUM 
L23456789012345678901234567890123456789 


Examples of invalid symbols: 


ABORT* (contains special character) 
1LAR (begins with a numeric) 
PAN N (embedded blank, symbol is pan) 


A 
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Reserved Symbols 


The ASM68K Assembler contains several reserved symbols, or keywords, that you 
cannot redefine. These reserved symbols are the symbolic register names used to 
denote the various hardware registers; they will not appear in a symbol table or in 
a cross-reference listing. Reserved Symbols are shown in Table 2-2. 


Table 2-2. Summary of Reserved Symbols 


Hardware Registers Reserved Symbols 


32-bit Address Registers AO, Al, A2, A3, A4, A5, A6, A7, SP 


32-bit Data Registers DO, D1, D2, D3, D4, DS, D6, D7 
Control Registers PC, SR, CCR, USP 

68010 Registers VBR, SFC or SFCR, DFC or DFCR 
68020 Registers CACR, CAAR, MSP, ISP 


68020 Psuedo Registers ZAO, ZAI, ZA2, ZA3, ZA4, ZAS, ZAG, ZA7, 
ZD0, ZD1, ZD2, ZD3, ZD4, ZD5, ZD6, ZD7, 


ZPC 

6888 1/82 Registers FPO, FP1, FP2, FP3, FP4, FPS, FP6, FP7, 
CONTROL, STATUS, IADDR, FPCR, FPSR, 
FPIAR 

68851 Registers” VAL, CAL, SCC, CRP, SRP, DRP, TC, AC, 


PCSR, BADO, BAD1, BAD2, BAD3, BAD4, 
BADS, BAD6, BAD7, BACO, BAC1, BAC2, 
BAC3, BAC4, BACS, BAC6, BAC7 


68030 Registers” CRP, SRP, TC, TTO, TT1, MMUSR 
68040 Registers” DTTO, DTT1, ITTO, ITT1, URP 


© Reserved only during this mode. 


- You can also define keywords to represent these reserved symbols through the 


EQU directive. 
Example: 


COUNT Egu D4 
ADD.B #1, COUNT 


The above example is the same as ADD.B #1,D4, 


The reserved symbol NARG represents the number of arguments passed on a 
macro call. 
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Assembly Program Counter 


During the assembly process, the assembler maintains a variable that always 
contains the address of the current memory location being assembled. This variable 
is called the Assembly Program Counter. It is used by the assembler to assign 
addresses to assembled bytes, but it is also available to the programmer. The 
asterisk (*) is the symbolic name of the Assembly Program Counter. It can be used 
like any other symbol, but it cannot appear in the label field. 


The asterisk (*) can be used to express the idea that *=address of myself. 
Example: 


- ORG $10 
00000010 4EF8 0010 JMP ® 


The relative branch instruction is in location 10. The instruction directs the 
microprocessor to ‘‘jump to myself.’’ The program counter in this example 
contains the value 10 and the instruction will be translated to a relative jump to 
location 10 from location 10. This example is useful when waiting for an interrupt. 


The Assembly Program Counter should not be confused with the hardware Program 

Counter (PC). The PC always contains a value 2 bytes greater than the Assembly 
cx Program Counter, The PC contains the address of the next instruction to be 
executed. 


Microtec Research, Inc. 29 


a | 


Constants 


Assembly Language 


ED 


Constants 


A constant is an invariant quantity. It can be an arithmetic value or a character code. 
Arithmetic values can be represented in either integer or floating-point format. 


Integer Constants 
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In most cases, integer constants must be contained in one, two, or four bytes. When 
a constant is negative, its equivalent two’s complement representation is generated 
and placed in the field specified. The ranges per byte of constants are shown in 
Table 2-3. 


Table 2-3. Constant Value Range 


Number of Bytes Value Range 


1 (unsigned) 0 to 255 
2 (unsigned) 0 to 65,535 


4 (unsigned) 0 to 4,294,967,295 


1 (Two’s complement) -128 to +127 
2 (Two’s compiement) -32,768 to +32,767 
4 (Two’s compiement) -2,147,483,648 to +2,147,483,647 


Numbers whose most significant bit is set can be interpreted either as a large 
positive number or a negative number. For example, the one byte number $FF may 
be either +255 or -1 depending on the use. The assembler will correctly recognize 
numbers in either form; however, you are generally responsible for their 
interpretation. 


All constants are evaluated as 32-bit quantities, i.e, modulo 232, Whenever an 
attempt is made to place a constant in a field for which it is too large, the assembler 
generates an error message. 


Decimal constants can be defined as a sequence of numeric characters optionally 
preceded by a plus or a minus sign. If unsigned, the value is assumed to be positive. 
Constants with bases other than decimal are defined by specifying a coded 
descriptor or special character before or after the constant. Motorola uses special 
characters to indicate base. 


Table 2-3 shows the available descriptors and their meanings. If no descriptor is 
given, the default number base is decimal. 
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Table 2-4. Summary of Descriptors 


Constants 


Examples: 


The following examples show how integer constants can be specified. 


t21_a 
t21_b 
t2l_ic 
t21.da 
t2le 
t21_f 
t21_h 
t21_i 
t21_j 


equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 


dc.b 
dc .b 
dec .b 
dac.b 
dc .b 
de .b 
de.b 
dc.b 
dc.b 


Floating-Point Constants 


$10101 
10101b 


$102101 
10101b 
@25 


sbinary 
;binary 
yoctal 
7octal 
;octal 
;decimal 
;decimal 
shex 
phex 


zbinary 
sbinary 
yoctal 
soctal 
poctal 
;decimal 
;decimal 
yhex 
thex 


Floating-point numbers can be in either decimal or hexadecimal format. A decimal 
floating-point number must contain either a decimal point or an E indicating the 
beginning of the exponent field. 


Examples: 


3.14159 
~22E-100 


9-22 * 107200 


Underscores can be placed before or after the E to increase readability. Underscores 
are ignored in determining the value of a constant as shown in Figure 2-1. 


A hexadecimal floating-point number is denoted by a colon (:) followed by a series 
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of hex digits up to 8 digits for single precision, 16 digits for double precision, or 24 Q 
digits for extended precision or packed decimal. The digits specified are placed in 

the field as they stand; you are responsible for determining how a given floating- 

point number is encoded in hexadecimal digits. If fewer digits than the maximum 

permitted are specified, the ones that are present will be left-justified within the 

field. Thus, the first digits specified always represent the sign and exponent bits. 


Floating-point constants are permitted only in the DC, DCB, and FEQU directives. 
Additional information about floating-point constants appears in the description of 
the DC directive in the Assembler Directives chapter of this manual. 
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Line Address 
SYMi =FEQU :1234_5676_9ABC_DEF_ 
S¥H2 FEQU :1234567B9ABCDEF 


6e888888 1234 567B SABC DC.x SYM1 
DEFB 8888 gage 
@B88888C 1234 5676 SABC OC.X SYM2 
DEFB 6888 Banb 
GBe888818 1234 S678 SABC bc.xX 71234_S676_QABC_DEF_ j;hexadecimal representation 
DEFB eaea Baa 
3 of Floating-point numbers 
8008824 1234 5678 SABC DE .X 11234S6789ABCOEF 3 using underscores 
DEF@ 9688 9008 
88888639 4B8F B98 CBE OC .X 3SE42 jdecimal representation a“ ; 


1 
2 
3 
4 
Ss 
6 
7 
8 
3 


EGBA AD7B 4E36 : 
B8BBBB3C 4HEF BBG CBES DC.X 35_E_42 > Of floating-point numbers 
EG6A AD7B 4656 


J 
o 


- 
pe 


3; ustng underscores 


N 


END 


Figure 2-1. Floating-Point Representation With and Without Underscores 
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An ASCH or EBCDIC character constant can be specified by enclosing one or more 
characters within quote marks and preceding them with an A for ASCTI or an E for 
EBCDIC. If you do not supply a descriptor, the default string format is ASCII. 


A character constant consists of up to four characters and corresponds to the field 
sizes shown in Table 2-5, 


Table 2-5. Character Constant Field Sizes 


Number of Characters Field Type 


1 8-bit byte 
16-bit 
32-bit 


U 
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Constants shorter than the length of the field are left-justified within the field, and 
the remainder of the field is filled with zeros. The size of the field is determined by 
the instruction word size which is ‘‘word’’ by default. 


Examples: 


ADD.B #'Z',D2 

EOR #£'0',CCR zin hex: F000 
ANDI #A'aB',D7 

MOVE.L #'JUMP', (A2) 


When character strings are used as operands of word and longword operations, the 
assembler assigns values according to the following rules which are compatible 
with the Motorola M68000 Family Resident Structured Assembler: 


1. 
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In DC directives, character strings are always left-justified in words or 
longwords. Any remaining bytes on the right of the word or longword are 
filled with zeros. 


DC.L 'ABCD' 
DC.L ‘ABCDE' 


Hex value 41424344 
Hex value 4142434445000000 


Example: 
DC.B ‘At ; Hex value 41 
DC.B ‘'AB' ; Hex value 4100 
Dc.W TAT + Hex value 4100 
DC.W 'AB' : Hex value 4142 
DC.W 'ABC' ; Bex value 4142 4300 
DC.L 'A' + Hex value 41000000 
DC.L ‘AB! ; Hex value 41420000 
DC.L ‘ABC’ + Hex value 41424300 

7 


In any other context, the justification depends on the number of characters 
in the string. Strings that are 1 or 2 characters long are left-justified to the 
nearest word boundary. Strings that are 3 or 4 characters long are left- 
justified in the longword. Remaining bytes on the right are zero-filled. 


Example: 


MOVE.B #'A',DO 
MOVE.W #'A',DO 
MOVE.W #'AB", DO 
MOVE.L #'A™,DO 
MOVE.L #'aB',DO 
MOVE.L #'ABC',DO 
MOVE.L #'ABCD',DO 


Valued moved is hex 41 
Valued moved is hex 4100 
Valued moved is hex 4142 
Valued moved is hex 00004100 
Valued moved is hex 00004142 
Valued moved is hex 41424300 
Valued moved is hex 41424344 


ed 


2-13 


Expressions 


Assembly Language 


You must use two single quotation marks to generate code for a single quotation 
mark in a character constant or string. 


Example: 
1 DON tT T ' 


The code for a single quotation mark will be generated once for every two quote 
marks that appear contiguously within the character string. 


Expressions 
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An expression is a sequence of one or more symbols, constants, or other syntactic 
structures separated by arithmetic operators. The maximum number of symbols in 
an expression is 48. Expressions are evaluated left to right, subject to the 
precedence of operators shown in Table 2-6. Parentheses can be used to establish 
the correct order of the arithmetic operators, and it is recommended that they be 
used in complex expressions involving operators such as >>, &, =, etc. 


The == operator is used to determine whether an operand exists. This is further 
described in the section Macro Call of Chapter 7, Macros. 


The comparison operators =, >=, etc., retum a logical true (all one bits) if the 
comparison is true and a logical false (zero) if the comparison is not true. All 
operands are considered to be unsigned 32-bit values and the comparison is 
unsigned. Comparisons against 0 are not very useful. 


Example: 

IF DATA=5 
The shift operators (>>, <<) shift the argument that goes before the operator right 
or left the number of bits specified by the argument that follows the operator. Zeros 
are shifted into the high or low order bits. 
Example: 


DC.B 2<<BIT 


Note 


Embedded blanks are not allowed in expressions. The 
assembler interprets spaces as termination characters. 
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Table 2-6. Precedence of Operators 


Precedence Operator Meaning 


(test for existing operand) 
(unary plus) 
(unary minus) 
(logical NOT) 
SIZEOF. (size of combined section) 
STARTOF. (start of combined section) 
>> (shift right) 
(shift left) 
Gogical AND) 
(logical OR) 
(exclusive OR) 
(multiplication) 
(division) 
(addition) 
(subtraction) 
~ (equality, not equality) 
(greater than, greater than or equal) 


(less than, less or equal) 


All expressions are evaluated modulo 22 and must resolve to a single unique value 
that can be contained in 32 bits. Consequently, character strings longer than four 
characters are not permitted in expressions. Whenever an attempt is made to place 
an expression in a one or two byte field and the calculated result is too large to fit, 
an error message is generated. 


Examples of valid expressions: 


PAM+3 LOOP+ (ADDR>>8) 
{(PAM+$45) /CAL VAL1=VALZ 
IDAM&255 


é. 


sot, 
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<SSTARTOF. and .SIZEOF. Operators 


The STARTOF. and .SIZEOF. operators help you to write code that initializes or 
copies logical sections of memory. When using the STARTOF. and .SIZEOF. 
operators, the section that is being referenced should be previously defined with the 
SECT or COMMON directive within the same assembly file. If this is not done, 
the assembler will create the section and its combine type; this combine type may 
not be desirable and could cause section mismatch errors at link time. 


For example, if your assembly file contains an instruction that creates a non- 
common section named ‘‘stack’’: 
move #.SIZEOF. (stack) ,DO 


and the linker command file contains a directive that creates a common section 
named ‘‘stack’’: 


common stack = $1FF 


the linker will generate a ‘‘section mismatch’’ error at link time. To solve this 
problem, create the common section ‘‘stack’’ before the .SIZEOF. operator is 
used: 


COMMON stack 
SECT code 


Tove #.SIZEOF. (stack) ,DO 


-STARTOF. Operator 


The STARTOF. operator gives the starting address of the combined section in 
which the named subsection will be contained, 


Syntax: 
-STARTOF . (Section_name) 
Description: 
section_name The name of a section. 
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-SIZEOF. Operator 


-STARTOF. and .SIZEOF. Operators 


The .SIZEOF. operator gives the size of the combined section. 


Syntax: 


. SIZEOF . (S€ction_name) 


Description: 


section_name The name of a section. 


Each STARTOF. and .SIZEOF. operator gives a relocatable value. 


Example: 


* This routine will clear memory for the full address 
* range of the final combined section that contains 
® the subsection zerovars from this module. 


OPT 
SECT 
DS.B 


SECT 
LEA 
MOVE 
initsect: CLR 
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CASE,D 
zerovars,,D 
$300 


code, ,C 
.STARTOF. (zerovars),AO ; start of section 
#.SIZEOF. (zerovars) ,D1; length of section 


(A0) + ; clear the address 
#1,D1 ; decrement counter 
initsect ; continue looping until count=0 


; otherwise return to calling routine 
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Introduction 


This chapter describes: 


* The 68000/10/20/30/40, CPU32, 68881/82, and 68851 assembly 
language instruction mnemonics and qualifiers. 

« How the assembler will generate code for variants of certain instructions 
depending on the instruction’s operands. 


Motorola Compatibility 


The assembler instruction mnemonics and the legal operands for various 
instructions afe identical to those defined by Motorola in the following 


publica 
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tions: 
MC68000 16/32-bit Microprocessor User's Manual, fourth edition 
(M68000UM(AD4)) 
M68000 Family Resident Structured Assembler Reference Manual 
(M68KMASM/D10) 
MC68020 32-Bit Microprocessor User’ s Manual, second edition 
(MC68020UM/AD REV 1) 


MC68030 32-Bit Microprocessor User’s Manual 
(MC68030UM/AD) 


MC68040 Enhanced 32-Bit Third Generation Microprocessor User's 
Manual 

(MC68040UM/AD) 

MC68040 Enhanced 32-Bit Third Generation Microprocessor Program- 
mer’s Reference Manual 

(MC68040RM/AD) 

MC68851 Paged Memory Management Unit User's Manual 
(MC68851UM/AD) 

MC68881/MC68882 Floating-Point Coprocessor User’ s Manual 
(MC68881UM/AD) REV 1 


Motorola CPU Central Processor Unit Reference Manual 
(CPU32RM/AD) 
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Motorola Compatibility Instructions 


In some cases, the Motorola assembler manua! and the Motorola processor manuals 
define different mnemonics for the same operation. Wherever possible, ASM68K 
recognizes both sets of mnemonics. However, the following case cannot be 
reconciled: 


DIVS.L <ea>,Dq :Dq is both upper and lower half of 
764-bit dividend 

DIVU.L <ea>,Dq *Dq is both upper and lower haif of 
764-bit dividend 


These instructions divide a 64-bit dividend by a 32-bit divisor and put a 32-bit 
quotient into pq. The 64-bit dividend is formed by using pq as both the upper-half 
and the lower-half of the number which is not a useful operation. 


The ASM68K Assembler’s behavior contradicts the description in Motorola’s 
MC68020 32-bit Microprocessor User's Manual. However, ASM68K behaves 
consistently with the documented M68000 Family Resident Structured Assembler. 


To divide a 32-bit dividend and obtain a 32-bit quotient, write the following 
instruction: 


DIVSL.L <ea>,Dq ; 32/32 ==> 32g 
TDIVS.L <ea>,Dq ; 32/32 ==> 32q 
DIVUL.L <ea>,Dq + 32/32 ==> 32q 
TDIVU.L <ea>,Dq : 32/32 ==> 32q 
The preferable way to divide a 64-bit dividend is: 


DIVS.L <ea>,Dr:Dq ; 64/32 ==> 32q,32r 
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Instruction Qualifiers 


In some cases, instruction mnemonics may have a qualifier (also called an 
extension), which is separated from the mnemonic by a period. The typical use of 
the qualifier field is to specify the scope of operation of the instruction. For this 
purpose, the recognized codes are .B (byte), .W (word), and .L (longword). If an 
instruction, which can have more than one qualifier, is coded without a qualifier, 
.W is the default. A few instructions use the qualifier field to force the assembler to 
override its defaults in choosing the short or long form of an instruction. The 
recognized codes in this case are .S (short) and .L (long). 


Floating-point coprocessor instructions use the .W, .B, and .L integer qualifiers as 
well as additional qualifiers that indicate real number precision. The floating-point 
qualifiers are .S for single precision real, .D for double precision real, .X for 
extended precision real, and .P for packed decimal string real. 


Table 3-1 shows the qualifiers used by the processor and coprocessor instructions 
shown in Tables 3-2 to 3-4. 


Table 3-1. instruction Qualifiers 


Qualifier Meaning . 


68000 size specifier, specifies signed integer data 
type of byte (8 bits), 
Double precision real (64 bits). 


One of the 3 floating-point system control registers 
(CONTROL, STATUS, or JADDR). 


One of the 8 floating-point data registers. 


68000 size specifier; specifies signed integer data 
type of long word (32 bits). 


Packed Decimal (BCD) string real (96 bits, 12 
bytes). 


Single precision real (32 bits). 


68000 size specifier; specifies signed integer data 
type of word (13 bits), 


Extended precision real (96 bits). 


1. Floating-point data type. 
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A list of the allowable 68000/10/20/30/40 and CPU32 instruction mnemonics is 
shown in Table 3-2. The legal! instruction qualifiers for each are listed. Notes are 
used to provide additional information and are described in more detail following 
the table. The notation cc (lowercase) represents one of the condition codes: T, F, 
Hi, LS, CC or HS, CS or LO, NE, EQ, VC, VS, PL, MI, GE, LT, GT, or LE. If 
no qualifiers are listed after a mnemonic, none are legal. 


Table 3-2. 68000/10/20/30/40 and CPU32 Instruction Mnemonics 


Mnemonic Qualifier Supported By 
CPU32 68000 10 20 3040 


ABCD 

ADD 

ADDA 

ADDI 

ADDQ 
ADDX 

AND 

ANDI to CCR 
ANDI to SR 
ANDI to other 
ASL 

ASR 


rerere 


fffEE HELL EE 
a Spee Sel rad 

MO OK Km OK OOK 
ee a! 
Pe i i i i i i i i Tel 
OK OOO OKO OO 
we OK OO OOK OKO OO 
Me wm mK KO OOO tt 


S 
(BT and BF are 


invalid; use BRA) 
B L 
B L 


~ Km mK Oe 
bt i i i i i oi oie ol 
Pr i i i i i od oo] 


x KM uM 
~~ eM OM 
x ~*~ MM OK 


(cont) 
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Table 3-2. 68000/10/20/30/40 and CPU32 tnstruction Mnemonics (cont.) 
Qualifier Supported By 


CPU32 68000 10 20 3040 


fee E=E 


(DBRA is also legal; 
same as DBF) 
WwW 


EORI to SR 
EORI to CCR 
EORI to other 
EXG 

EXT 

EXTB 
EXTW 
FABS 

FADD 

FBcc 

FCMP 


x Mu uM me em KK Om 
x mM em OO OOK 
~~ Km mw mK KO OO 
x eK KK MH HK 
xe eM KR KK HR mM em 


Pad 


x 
XK 
x 
x 
x 
x 
xX 
x 
x 
Xx 
x 
x 
x 
x 
x 
xK 
x 


“x Ke MK MR KK Km mK me OK Om OM 


(cont.) 
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Instructions 


Table 3-2. 68000/10/20/30/40 and CPU32 Instruction Mnemonics (cont.) 


Qualifier 


MOVE from CCR 
MOVE to CCR 
MOVE to/from SR 
MOVE to/from USP 
MOVE other B 
MOVE]16 

MOVEA 

MOVEC 

MOVEM 

MOVEP 

MOVEQ 

MOVES 

MULS 

MULU 


fe €£ HEE FELHE 


cr 


Pree rere 


Supported By 


CPU32 68000 10 20 3040 


x 
x 
x 
x 
Xx 
x 
x 
x 
x 
X 
x 
x 
x 


i i i i ole) 


mM OO KOO KOO 


~ mm OK 
~ om KO 
x x mM me 


mm mm Km mK KO x em me OM OM 
a eK Hw KM MK 
em em mK MK 

bit i i i i i i oi oi eM oda! 


~ OM 
mM KM OKO 


(cont.) 
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Table 3-2. 68000/10/20/20/40 and CPU32 Instruction Mnemonics (cont.) 
Supported By 


Mnemonic 


NBCD 
NEG 
NEGX 
NOP 

NOT 

OR 

ORI to CCR 
ORI to SR 
ORI to other 
PACK 
PEA 
PFLUSHAN 
PFLUSHN 
PTEST 
RESET 
ROL 

ROR 
ROXL 
ROXR 
RTD 

RTE 

RTM 

RTR 

RTS 
SBCD 

Sec 

STOP 
SUB 
SUBA 
SUBI 
SUBQ 
SUBX 
SWAP 
TAS 
TBLS 
TBLSN 
TBLU 
TBLUN 
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CPU32 68000 10 20 3040 


m= eK em KK 


mK em mm KO 


x KK Hw KR KKK KM mK mm OK 


x «He HM MH HM OO 


Ye 


xe Kw mR HM 


» 


Pr i i el 


x KM HK MK OM 


eM KK HK KK KK Km mR 


at i we! 


x 
x 
x 
Xx 
x 
x 
x 
X 
x 
x 
x 
x 
x 
x 
x 
x 
xX 
x 
x 
x 


x He mM HK OO 


~*~ «uM HM OKO KO OOK OKO 


} i i i i de i i i oe oi ot od ot oo ol oS ot a 


~ wu Mm mK mM Om KOK 
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Table 3-2. 68000/10/20/30/40 and CPU32 Instruction Mnemonics (cont.) 


Qualifier Supported By 
CPU32 68000 10 20 3040 


(same ans 
(same = DIVUL) 
WL 
WL 


B WL 


x xX 
xX Xx 
xX X 
xX X 
kK K 
x XxX 
x XxX 
x xX 


x eK uM KR HM mK 
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Instruction Qualifiers 


Note 


. 68020/30 and CPU32 instruction only. Its use when not in 


68020 mode (CHIP 68020, CHIP 68030, OPT P=68020, or 
OPT P=68030) will cause a warning. 


2. Illegal in 68000 mode. 
. The .L qualifier is valid only in 68020/30/40 and CPU32 


modes. 


. There are three distinct Extend operations: Extend Byte to 


Word, Extend Word to Long, and Extend Byte to Long. 
Extend Byte to Word may be coded as EXT.W or EXTB.W. 
Extend Word to Long may be coded as EXT.L or EXTW.L. 
Extend Byte to Long, which is valid in 68020/30 and CPU32 
modes only, must be coded as EXTB.L. 


. TRAPcc, Tec, and TPcc are different mnemonics for the 


same instructions. TRAPcc can have an optional operand. 
Tec cannot have an operand, and TPcc must have an 
operand. 


. For branch instructions, the legal qualifiers and their mean- 


ings are different depending on the mode setting (CHIP or 
OPT P= directive). In modes other than 68020/30/40 and 
CPU3z2, only the .L and .S qualifiers are permitted. .S forces 
a byte instruction and .L forces a word instruction. In 68020/ 
30 and CPU32 modes, ali four qualifiers are allowed. .B or 
.§ forces a byte instruction and .W forces a word instruction. 
-L forces a longword instruction, unless the OPT OLD di- 
tective was used, in which case .L forces a word instruction. 
(OPT OLD is intended to permit the assembly of existing 
programs without changing all the .L qualifiers to .W). 


. For the single-bit instructions, the generated code is fully 


8. 
9. 


10. 
11. 
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determinable from the operands and, therefore, the qualifier 
serves no function. For Motorola compatibility, however, the 
qualifiers .B and .L are accepted and, if a qualifier is present, 
the operands are checked to be sure they match the qualifier. 


CPU32 instruction only. 

68020/30/40 instruction only. 

Added or modified for 68040. 

Instruction common to 68040 and 6888 1/82. 
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Table 3-3 contains instruction mnemonics for the 68881/82 floating-point 
coprocessor. Legal instruction qualifiers for each are listed. Notes are used to 
provide additional information and are described in more detail following the table. 


The notation cc (lowercase) represents one of the condition codes: GT, GE, LT, 
GL, LE, GLE, SEQ, ST, NGT, NGE, NLT, NGL, NLE, NGLE, SNEQ, SF, 
OGT, OGE, OLT, OGL, OLE, OR, EQ, T, ULE, ULT, UGE, UEQ, UGT, UN, 
NEQ, or F. If no qualifiers are listed after a mnemonic, none are legal. 


Table 3-3. 68881/82 Floating-Point Coprocessor Instruction Mnemonics 
Note Mnemonle Qualifier 


FABS 

FACOS 

FADD 

FASIN 
FATAN 
FATANH 
FBcc 

FCMP 

FCOS 

FCOSH 

FDBcc 

FDIV 

FETOX 
FETOXMI 
FGETEXP 
FGETMAN 
FINT 

FINTRZ 
FLOG10 
FLOG2 
FLOGN 
FLOGNPIL 
FMOD 
FMOVE to FPn 
FMOVE from FPn 
FMOVE FPcr 
FMOVECR 
FMOVEM FPn 
FMOVEM FPcr 
FMUL 


€= 
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oO VevvTOoCvvoVCvVYD vouv oVVvoUY 


woaonmmwww 
PAK KKK Oh OK OK OS OO OOS OK OO OO KK Od OO OOS 


vu vu vU'U'U'Y 


ANAANMNMNAUMUNNDA ANN AAN 


& 2428 E€ E822 e EEE Ff Ee ESE 
VoyvuUVUU Vy UU UD 


BD WWW KWOnWP eee ee 
SOP eRr eee Ore Ce eee Oe ee Mere reeerek 


wn 
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= 
0 
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(cont.) 


Microtec Research, Inc. 


U 


OU 


O 


a Instructions Instruction Qualifiers 
; 


Table 3-3. 68881/82 Floating-Point Coprocessor Instruction Mnemonics (cont.) 
Note Mnemonic Qualifier 
BW LSDXP 


BW LS DXP 


C 
wn 
a] 


(dual monadic) 


SBUuUtBnmwwmwdwuww 
SEE HESS HST SEL EEE = 
Cee Pree reer ee er 
ANNANARNAN 
ouou00C0v7o0 8 
mK OS PK KOK EK OO OK 
VvuvuvuyuU oY 


3 
4 
2 
5 
5 
2 
4 
2 
2 
3 
3 
3 
3 
2 
3 
3 
3 
5 
5 
5 
4 
3 


< 
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Note 


68881/82 Data Movement instruction. Moves operands into, 
between, or out of the floating-point data registers. 


. 68881/82 Dyadic Operation instruction. Performs arithmetic 


operations requiring two operands, e.g., subtract. One of the 
operands is always from a floating-point data register. The 
other may be from a memory address register, from an integer 
data register, or from a floating-point data register. The result 
is stored in a floating-point data register. 


. 68881/82 Monadic Operation instruction. Performs arithmetic 


operations that require only one operand, e.g., cosine. The 
operation is performed on the source operand. The result is 
stored in a destination which is always a user-specified 
floating-point data register. 


. 68881/82 Program Control instruction. Tests an instruction 
operand for condition codes set in a floating-point status 
tegister. The branch instructions within this group let you set a 
variable based on the floating-point condition codes. You can 
then use this variable in other program and system control 
instructions. 


. 68881/82 System Control instruction. Communicates with the 


operating system using a conditional trap instruction. This type 
of instruction utilizes the same conditional tests as the program 
control instruction and additionally allows a 16- or 32-bit 
operand for the purpose of passing information to the operating 
system. 


. FTRAPcc, FT cc, and FTPcc are different mnemonics for the 


same instructions. FTRAPcc can have an optional operand. 
FTcc cannot have an operand, and FTPcc must have an 
operand. 
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Table 3-4 contains instruction mnemonics for the 68030 and/or 68851 paged 
memory management instruction mnemonics. Notes are used to provide additional 
information and are described in more detail following the table. 


Table 3-4. 68030/68851 Paged Memory Management instruction Mnemonics 


Note Mnemonic Qualifier 


1 
1 
2 
2 
1 
1 
2 
2 
1 
3 
3 
1 
1 
1 
2 
2 
1 
1 


Note 


1. 68851 memory management instruction only. 
2. 68851/68030 memory management instruction. 


3. 68030 memory management instruction only. 
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The assembler lets you use generic instruction types when writing your programs, 
and it will generate code for variants of the instruction where appropriate. The 
assembler generates code for variants of an instruction either because the variant 
form is implied by the operands or because fewer bytes of code are generated for 
the variant instruction. 


The variants recognized by the assembler are shown in Table 3-5. 


Table 3-5. Summary of Variants of instruction Types 


Generic Variants 


ADD, ADDA, ADDQ, ADDI 


AND, ANDI 
CMP, CMPA, CMPM, CMPI 
EOR, EORI 
MOVE, MOVEA, MOVEQ 
OR, ORI 
SUB, SUBA, SUBQ, SUBI 
Example: 

D250 ADD {(AQ)},D1 

D2D0 ADD (A0O},Al1 ; ADDA 

5E50 ADD #7, (AQ) :; ADDO 

0650 FFFF ADD #$ff£f£f, (ad) # ADDI 


When the ADD and SUB instructions have operands which are legal for either the 
ADDQ or the ADDI variant (e.g., #1,D4), the assembler chooses ADDQ or SUBQ 
because these instructions are two bytes shorter than ADDI. You can, however, 
force the ADDI form by specifying ADDI as the mnemonic. 


We recommend that you use the mnemonics of the variant forms because the 
resulting code is easier to understand. 
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Instruction Operands 


In general, instructions have zero, one, two, or three operands, and in some cases 
the same mnemonic may take different numbers of operands to indicate different 
functions. Not all addressing modes are necessarily legal for a particular operand of 
a particular instruction, The legal addressing modes for an operand vary in an 
irregular way, which is fully described in the publications listed in the Motorola 
Compatibility section at the beginning of this chapter. 


instruction Operands 


Note that there are minor differences in legal addressing modes between the 
CPU32, 68020/30/40, and other 68000 family chips, which are described in detail 
in the Motorola manuals. 


Registers 


The assembler recognizes the register mnemonics listed and described in Table 
3-6. Register mnemonics can be uppercase or lowercase and are reserved symbols. 


Register 
Mnemonic 


AC 
BACO0-BAC7 


BADO-BAD7 


CAAR 


CACR 


CAL 
CCR 


Table 3-6. Summary of Register Mnemonics 


Description 


32-Bit Address Registers. 
16-Bit Access Control Register. 


Eight 16-Bit Breakpoint Acknowledge 
Control Registers. 


Eight 16-Bit Breakpoint Acknowledge 
Data Registers. 


Cache Control Register. Holds the 
address for cache control functions. 


Cache Control Register. Holds the 
address for cache control functions. 


8-Bit Protection Control Register. 
Condition Code Register. CCR is the 


lower eight bits of the status register (SR). 


CONTROL/FPCR 


Floating-Point Control Register. 
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CPU32, 68000/10/20/30/40 
68851 


68851 


68851 


68020/30/40 


68020/30/40 
68851 


CPU32, 68000/10/20/30/40 


68040, 6888 1/68882 
(cont.) 
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Register 
Mnemonic 


CRP 
DO-D7 
DFC/DFCR 


DRP 
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Instructions 
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Table 3-6. Summary of Register Mnemonics (cont.) 


Description 


64-Bit User Root Point Register. 
32-bit Data Registers. 


Alternate Function Code Destination 
Register. 


64-Bit DMA Root Point Register. 
Transparent Translation Registers. 
Floating-Point Data Registers. 


Floating-Point Instruction Address 
Register. 


Interrupt Stack Pointer 
(68020/30 interrupt state). 


Transparent Transiation Registers. 
MMU Status Register 


Master Stack Pointer 
(68020/30 supervisor state). 


Program Counter (used in PC-relative 
addressing modes).The program counter 
contains the address of the location two 
bytes beyond the beginning of the currently 
executing instruction. The user mnemonic 
PC does not directly access the program 
counter register but forces the use of 
program counter relative addressing modes. 


16-Bit Cache Status Register. 
16-Bit Status Register. 


8-Bit Protection Control Register. 


Supported By 


68030/40, 68851 
CPU32, 68000/10/20/30/40 


CPU32, 68010/20/30/40 
68851 

68040 

68040, 6888 1/68882 


68040, 68881/68882 


68020/30 
68040 
68030 


68020/30 


CPU3?2, 68000/10/20/30/40 
68851 
68851 
68851 


(cont.) 
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Registers 


Register 
Mnemonic 


SFC, SFCR 
SR 


SRP 
SSP/A7 


STATUS/FPSR 


Table 3-6. Summary of Register Mnemonics (cont.) 


Description 


Alternate Function Code Source Register. 


Status Register. All 16 bits can be modified 
in the supervisor state. Only the lower 8 
(CCR) can be modified in the user state. 


64-Bit Supervisor Root Point Register. 


System Stack Pointer. SSP only legal for 
68000/10. 


Floating-Point Status Register. 

32-Bit Translation Control Register. 
32-Bit Transparent Translation Registers. 
16-Bit MMU Status Register. 

User Root Pointer Register 

User Stack Pointer (for user state). 

8-Bit Protection Contro} Register. 


Vector Base Register. Used for multiple 
vector table areas. 


Suppressed Address Registers. The register 


specified is used in the instruction, but its 


value is considered zero for effective address 


calculations. 


Suppressed Data Registers. The register 
specified is used in the instruction, but its 


value is considered zero for effective address 


calculations. 


Suppressed Program Counter. The PC is 
used in the instruction, but its value is 
considered zero for effective address 
calculations. 
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Supported By 


CPU32, 68000/10/20/30/40 


CPU32, 68000/10/20/30/40 
68030/40, 68851 


68040, 68881/68882 
68030/40, 68851 

68030 

68030 

68040 

CPU32, 68000/10/20/30/40 
68851 


CPU32, 68010/20/30/40 


CPU32 


CPU32 


Registers 


Instructions 


The 68881/82 floating-point coprocessor uses the 68020 instruction set and 
addressing modes to provide a logical extension to the integer capabilities of the 
68020 processor. In addition to the eight 32-bit Address Registers (AO to A7) and 
eight 32-bit Integer Data Registers (D0 to D7) of the 68020, the 68020/68881/ 
68882 processor combination provides eight Floating-Point Data Registers (FP0 to 
FP7). 


The 6888 1/82 interfaces to the 68020 in a way that is transparent to you. You access 
the floating-point registers of the 68881/82 as though they were resident in the 
68020. The 68881 /82 coprocessor interface places no restrictions on the use of the 
68020 registers. Floating-point operations are coded exactly the same as integer 
operations. 
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Introduction 
This chapter describes: 
* The addressing modes for the 68000/08/10, CPU32, and 68020/30/40 
processors. 
e Assembler syntax and the addressing modes that are generated for a 
particular syntax. 


» How you can control generation of addressing modes by setting or 
clearing various assembler options (with the OPT directive). 


The 68020 and 68030 addressing modes and memory ranges are the same as those 
of the 68040. The 68020 mnemonics with the exception of CALLM and RTM, 
however, are a subset of the 68030. 


Addressing Modes 


C Table 4-1 lists the addressing modes that are defined for all chips. These modes are 
ee described in more detail in the following sections. 


a 
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Addressing Modes 


Register Direct Modes: 
Address Register Direct 
Data Register Direct 


m Addr Modes: 


Address Register Indirect 

Address Register Indirect with 
Postincrement 

Address Register Indirect with 
Predecrement 

Address Register Indirect with 
16-bit Displacement 

Address Register Indirect with 
8-bit Displacement and Index 

Address Register Indirect with 
Base Displacement and Index 

Memory Indirect Post-Indexed 

Memory Indirect Pre-Indexed 


Memory Reference Modes: 

Absolute Short Address 

Absolute Long Address 

Program Counter Indirect with 
16-bit Displacement 

Program Counter Indirect with 
8-bit Displacement and Index 

Program Counter Indirect with 
Base Displacement and Index 

Program Counter Memory Indirect 
Post-Indexed 

Program Counter Memory Indirect 
Pre-Indexed 


Non-Memory Reference Modes: 


Immediate 


Table 4-1. Addressing Modes YQ 


68000/08/10 CPU32 68020/30/40 
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The various Program Counter relative modes all refer to a memory address in terms 
of its distance from the instruction. At execution-time, the Program Counter will 
contain a value 2 greater than the beginning of the instruction, i.e., the address of 
the first byte of extension. 


The 68000/08/10 microprocessors can address odd-numbered memory locations 
only when the instruction is operating on a single byte. Neither the assembler nor 
the linker checks for this and, in many cases (such as indexed addressing modes), 
neither the assembler nor the linker is capable of checking for this situation. The 
CPU32 and 68020/30/40 have no such restriction. However, all chips require that 
instructions as opposed to data begin at an even address, and the assembler enforces 
this. 


Register Direct Modes 
The Register Direct Modes act directly on the contents of a register. 


All other modes specify an address in memory. The contents of this address are used 
as the instruction operand. . 


Address Register Direct 


The Address Register Direct Mode acts directly on the contents of an address 
register. 


Data Register Direct 

The Address Register Direct Mode acts directly on the contents of a data register. 
Memory Addressing Modes 

The Memory Addressing Modes alter memory contents. 


Address Register Indirect 


The Address Register Indirect Mode provides the memory address in an address 
register. 


Address Register Indirect with Postincrement 


The Address Register Indirect with Postincrement Mode provides the memory 
address in an Address Register and, after using the address, increments the register 
by one, two, or four depending upon whether the scope of the operation is byte (.B), 
word (.W), or longword (.L). 
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Address Register Indirect with Predecrement 


The Address Register Indirect with Predecrement Mode decrements an Address 
Register by one, two, or four depending upon whether the size of the operand is byte 
(.B), word (.W), or longword (.L) and then uses the resulting contents of the register 
as the memory address. None of the preceding modes require extension bytes. 


Address Register Indirect with 16-bit Displacement 


The Address Register Indirect with Displacement Mode calculates the memory 
address as the sum of the contents of an address register and a sign-extended 16-bit 
displacement. It requires 2 bytes of extension. 


Address Register Indirect with 8-Bit Displacement and Index 


The Address Register Indirect with 8-Bit Displacement and Index Mode calculates 
the memory address as the sum of the contents of an Address Register, the contents 
of an Index Register which may be an address or a data register, and a sign-extended 
8-bit displacement. It requires 2 bytes of extension. 


The Index Register involved may use either all 32 bits or 16 bits sign-extended. On 
the CPU32 and 68020/30/40, the Index Register contents may optionally be 
multiplied by a scale factor of 2, 4, or 8 before being added to the Address Register 
contents. 


Address Register tndirect with Base Displacement and index 


The Address Register Indirect with Base Displacement and Index Mode calculates 
the memory address as the sum of the contents of an Address Register, the contents 
of an Index Register which may be an address or a data register, and a sign-extended 
base displacement which may be either 16 or 32 bits. This mode requires at least 2 
bytes of extension plus 2 more for a 16-bit displacement or 4 more for a 32-bit 
displacement. 


The Index Register involved may use either all 32 bits or 16 bits sign-extended. The 
Index Register contents may optionally be multiplied by a scale factor of 2, 4, or 8 
before being added to the Address Register contents. Any or all of the Address 
Register, Index Register and displacement may be specified as null in which case 
they would have a value of 0. A null displacement does not require any extension 
bytes. 


Memory Indirect Post-indexed 
The Memory Indirect Post-Indexed Mode first calculates an intermediate address as 


the sum of the contents of an Address Register, and a sign-extended base 
displacement which may be either 16 or 32 bits. The final memory address is then 
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calculated as the sum of the contents of the intermediate address, the contents of an 
Index Register which may be an address or a data register, and an outer 
displacement which can be either 16 or 32 bits. This mode requires at least 2 bytes 
of extension plus 2 more for each displacement, which is 16 bits, and 4 more for 
each displacement, which is 32 bits. 


The Index Register involved can use either all 32 bits or 16 bits sign-extended. The 
Index Register contents can optionally be multiplied by a scale factor of 2, 4, or 8 
before being added to the intermediate address contents and the outer displacement. 
Any or all of the Address Register, Index Register, base displacement and outer 
displacement can be specified as null in which case they would have a value of 0. 
Null displacements do not require any extension bytes. 


Memory Indirect Pre-indexed 


The Memory Indirect Pre-Indexed Mode first calculates an intermediate address as 
the sum of the contents of an Address Register, an Index Register which can be an 
address or a data register, and a sign-extended base displacement which can be 
either 16 or 32 bits. The final memory address is then calculated as the sum of the 
contents of the intermediate address, and an outer displacement which can be either 
16 or 32 bits. 


This mode requires at least 2 bytes of extension plus 2 more for each displacement, 
which is 16 bits, and 4 more for each displacement, which is 32 bits. The Index 
Register involved can use either all 32 bits or 16 bits sign-extended. The Index 
Register contents can optionally be multiplied by a scale factor of 2, 4, or 8 before 
being added to the Address Register contents and the base displacement. Any or all 
of the Address Register, Index Register, base displacement and outer displacement 
can be specified as null in which case they have a value of 0. Null displacements do 
not require any extension bytes. 


Memory Reference Modes 


The various Program Counter relative modes all refer to a memory address in terms 
of its distance from the instruction. At execution-time, the Program Counter will 
contain a value 2 greater than the beginning of the instruction, i.e., the address of 
the first byte of extension. 


Absolute Short 


The Absolute Modes provide an actual memory address right in the instruction. For 
Absolute Short Mode this address is 16 bits sign-extended (2 bytes of extension). 
Since 16-bit addresses are sign-extended, the areas of memory addressable by 
Absolute Short Mode are from 0 to $7FFF plus an area in high memory dependent 
on the target chip: 
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1. From $FF8000 to $FFFFFF for the 68000/10 
2, From $F8000 to $FFFFF for the 68008 
3. From $FFFF8000 to $FFFFFFFF for the CPU32 and 68020/30/40 


Regardless of the target chip, the assembler recognizes only the absolute addresses 
from $FFFF8000 to $FFFFFFFF as being in the high short-addressable area of 
memory. If it is necessary to use Absolute Short Mode on the actual area of high 
memory that is short-addressable on the target chip, any absolute code should be 
placed in a separate module and referenced as XREF.S from other modules. This 
technique causes the use of Absolute Short addressing mode in most cases. 
Alternatively such code could be made relocatable and placed in a SECTIONS, 
then located correctly at link time. In this case, the high short-addressable code need 
not be in a separate module. 


Absolute Long 


Absolute Long Mode contains a full 32-bit address in the instruction and can 
therefore address any memory location on any chip (4 bytes of extension). 


Program Counter Indirect with 16-bit Displacement 


The Program Counter Indirect with 16-bit Displacement Mode calculates the 
memory address by adding the value of the Program Counter to a sign-extended 16- 
bit displacement. It requires 2 bytes of extension. 


When the target chip is the CPU32, 68020, 68030, or 68040, the Index Register can 
optionally be multiplied by a scale factor of 2, 4, or 8 before being added to the other 
components. 


Program Counter Indirect with 8-bit Displacement 


The Program Counter with 8-bit Displacement and Index Mode calculates the 
memory address by adding the value of the Program Counter, the contents of an 
Index Register (which may be Address or Data), and can use the entire 32 bits or 
the low order 16 bits, sign-extended, and a sign-extended 8-bit displacement. It 
requires 2 bytes of extension. 


When the target chip is the CPU32, 68020, 68030, or 68040, the Index Register can 
optionally be multiplied by a scale factor of 2, 4, or 8 before being added to the other 
components. 


Program Counter Indirect with Base Displacement and Index 


The Program Counter Indirect with Base Displacement and Index Mode calculates 
the memory address-by adding the value of the Program Counter, the contents of an 
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Index Register which may be an address or data, and can use the entire 32 bits or 
the low order 16 bits sign-extended, and a sign-extended displacement which may 
be either 16 or 32 bits. This mode requires at least 2 bytes of extension plus 2 more 
for a 16-bit displacement or 4 more for a 32-bit displacement. 


The Index Register may optionally be multiplied by a scale factor of 2, 4, or 8 before 
being added to the other components. Any or all of the Address Register, Index 
Register, and displacement may be specified as null in which case they would have 
a value of 0. A null displacement does not require any extension bytes. 


Program Counter Memory Indirect Post-Indexed 


The Program Counter Memory Indirect Post-Indexed Mode first calculates an 
intermediate address.as the sum of the contents of the Program Counter, and a sign- 
extended base displacement which may be either 16 or 32 bits. The final memory 
address is then calculated as the sum of the contents of the intermediate address, the 
contents of an Index Register which may be an address or a data register, and a sign- 
extended outer displacement which can be either 16 or 32 bits. This mode requires 
at least 2 bytes of extension plus 2 more for each displacement, which is 16 bits, and 
4 more for each displacement, which is 32 bits. 


The Index Register involved could use either all 32 bits or 16 bits sign-extended. 
The Index Register contents can optionally be multiplied by a scale factor of 2, 4, 
or 8 before being added to the intermediate address contents and the outer 
displacement. Any or all of the Program Counter, Index Register, base 
displacement, and outer displacement can be null, in which case they would have a 
value of 0. Null displacements do not require any extension bytes. 


Program Counter Memory Indirect Pre-Indexed 


The Program Counter Memory Indirect Pre-Indexed Mode first calculates an 
intermediate address as the sum of the contents of the Program Counter, an Index 
Register which can be an address or a data register, and a sign-extended base 
displacement which may be either 16 or 32 bits. The final memory address is then 
calculated as the sum of the contents of the intermediate address and a sign- 
extended outer displacement which can be either 16 or 32 bits. This mode requires 
at least 2 bytes of extension plus 2 more for each displacement, which is 16 bits, and 
4 more for each displacement, which is 32 bits. 


The Index Register involved can use either all 32 bits or 16 bits sign-extended. The 
Index Register contents can optionally be multiplied by a scale factor of 2, 4, or 8 
before being added to the Program Counter contents and to the base displacement. 
Any or all of the Program Counter, Index Register, base displacement, and outer 
displacement can be null in which case they would have a value of 0. Null 
displacements do not require any extension bytes. 
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Non-Memory Reference Modes ©?) 


These modes provide data directly to the instruction. 


Immediate 


The Immediate Mode provides data directly in the instruction. The number of bits 
used and the number of bytes of extension varies with the instruction and with the 
qualifier. Immediate data is always evaluated first as a 32-bit unsigned two’s 
complement value. If the instruction requires fewer than 32 bits, the most 
significant bits are checked and discarded. If the bits discarded are all 0 or all 1, the 
instruction assembles normally. If the bits discarded are mixed zeros and ones, a 
warning is printed. 

The immediate operands of ADDQ, SUBQ, TRAP, BKPT and all Shifts which are 
smaller than a byte cannot be relocatable or external. All other immediate operands 
can be relocatable or external. 


68881/82 Floating-Point and 68851 MMU 
Coprocessor and Addressing Modes 


The 68881/82 floating-point coprocessor and 68851 MMU use 68020/30/40 
addressing modes by requesting the processor to perform addressing mode * 
calculations based on 68881/82 and 68851 instructions. The 68881/82 and 68851 

know nothing about addressing modes. When instructed to do so by the 6888 1/82 

or 68851, the 68020/30/40 evaluates the instruction, transfers the operands through 

the coprocessor interface, and performs the addressing mode calculations. 


Any of the 68020/30/40 addressing modes described above can be used with 
floating-point instructions, including address/data register direct, indexed indirect, 
auto increment, auto decrement, and immediate mode. When a floating-point | 
instruction is encountered, the 68020/30/40 evaluates the instruction to its 
addressing modes. These include all legal 68020/30/40 addressing modes with the 
exception of a few restrictions for certain instructions. The exceptions are fully 
described in Motorola’ s Floating-Point Coprocessor User’s Manual. 


UO 
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Assembler Syntax for Effective Address Fields 


The assembler uses one of several possible addressing modes depending on the 
operand(s) specified. The following pages describe how the assembler makes such 
decisions. Table 4-2 provides a definition of terms used to describe operand syntax. 


Table 4-2. Assembler Syntax for Effective Address Flelds 


Represents an address register. 
Represents a data register. 


Represents either an address or data register, or a suppressed 
register (ZAn or ZDn). ASM68K does not recognize the 
mnemonic Rn. 


abs exp Represents an absolute expression, including an external 
reference with no section specified. 


rel_exp Represents a relocatable expression, including an external 
reference with a section specified. 


Represents either an absolute or relocatable expression. 


Represents an optional field. Commas within the brackets 
represent a choice of elements if the field is present. 


Addressing Mode Syntax 


ASM68K fully supports Motorola’s 68020/30/40-oriented syntax. This syntax uses 
square brackets, [ ], to designate the components of the intermediate address in the 
68020/30/40 addressing modes, and parentheses to group the other components of 
an effective address. The following facts apply to addressing mode syntax: 


¢ The syntax exp(anything) (old 68000) is equivalent to (exp,anything) 
(68020). 


¢ The order of items separated by commas within square brackets or 
parentheses (grouping characters) is not significant, unless there are two 
A registers or two ZA registers, neither having an appended size code 
nor scale factor present within the same grouping characters. In this case 
(which is syntactically ambiguous), the leftmost register is the Base 
Register and the rightmost is the Index Register. 
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* A 68000 mode will be chosen if this is a possible interpretation of the 
operand, as these modes are more efficient. However, any of the 
following is sufficient to force a 68020 addressing mode (perhaps with 
some null fields): 


1. Using a Z-register (ZPC, ZAn, or ZDn). 
2. Using square brackets. 


3. Specifying an explicit .L size code on a displacement. Note 
that a .W qualifier does not force a 68020/30 mode. For 
example: 

( (LABEL) .L, Al) 


4. Specifying a scale factor other than 1 on an index register. 


5. Specifying a displacement too large to fit in the 68000 mode. 
Forward references are assumed to require 32 bits, while 
externals and relocatables are assumed to require 16 bits (but 
if the absolute part of an expression such as reloct+abs is too 
big to fit in 16 bits, a 32-bit field will be used). These defaults 
may be overridden by explicit .W and .L codes and, if a 
forward reference is later found to fit in 16 bits after all, a 
68000 mode may be selected on pass 2 (some extra NOPs 
will trail the instruction). The OPT flags BRW and FRS do 
not apply to forward references which appear in conjunction 
with a register. 


Note that coding (exp,An) rather than exp(An) or specifying a scale factor of 1 
explicitly is not sufficient to force the use of 68020/30/40 modes. 


Errors will occur when assembler syntax forces 68020/30/40 addressing modes, and 
the target microprocessor specified with the CHIP or OPT P directives is not the 
68020, 68030, or 68040. You should note that: 


¢ Assembler syntaxes that generate Address Register Indirect with 
Displacement or Memory Indirect modes (e.g., (exp,An) or 
({exp,An],Rn)) allow exp to be an absolute or a relocatable expression. 
If exp is an absolute expression, the assembler will use it as the 
displacement. If exp is a relocatable expression, the syntax tells the 
assembler to access the location of the relocatable expression using 
register An indirect, and the linker will calculate the final displacement. 
The A2-A5 Relative Addressing section later in this chapter provides 
more information on this. 


¢ Absolute expressions in operands that generate Program Counter 
relative addressing modes (e.g., (abs_exp,PC)) can have two different 
meanings depending upon the assembler flag ABSPCADD. 
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By default, ABSPCADD is on, and the absolute expression is 
considered to be the address from which the current PC is subtracted to 
form the displacement, For example, BRA !abel(PC) branches to the 
location of label. 


When the ABSPCADD flag is off (by setting OPT NOABSPCADD or 
OPT -ABSPCADD), the absolute expression is the displacement. For 
example, BRA label{PC) branches to the address of the current PC plus 
the value of label. 


While you can use the OPT NOABSPCADD assembler option to code 
actual displacements in Program Counter relative instructions, there is 
also a way to specify actual displacements when the ABSPCADD flag 
is on. For example, if you would like to specify a displacement of +8 
from the current location counter, you could use the syntax (*+8,PC). 
This is equivalent to OPT NOABSPCADD and the syntax (6,PC). The 
PC is 2 greater than the * location counter symbol. 


In the discussion that follows, the 68020/30/40 notation is used, but the list above 
should be kept in mind. For example, the discussion of the operand 
(abs_exp,An,Rn{.W,.L}) includes the forms abs exp(An,Rn{.W,.L}) and 
(abs_exp,Rn{.W,.L},Ax). 


Operand Syntax and Addressing Modes 


The relationship between operand syntax and addressing modes is described below. 


Dn Operand 


The operand Dn always results in Data Register Direct Mode. 


An Operand 


The operand An always results in Address Register Direct Mode. 


(An) Operand 


The operand (An) always results in Address Register Indirect mode. 


(An)+ Operand 


The operand (Am)+ always results in Address Register Indirect with Postincrement 


Mode. 
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-(An) Operand 


The operands -(An) always result in Address Register Indirect with Predecrement 
Mode. 


exp Operand 


The operand exp results in Absolute Short Address, Absolute Long Address, or 
Program Counter Indirect with 16-bit Displacement Mode. The assembler chooses 
one of these modes based on rules described in this chapter. In most cases, good 
results will be obtained by allowing the assembler to use its default action. 


#exp Operand 


The operand #exp results in the Immediate Mode. An absolute expression must be 
within a certain size range that is dependent on the instruction and qualifier code. 
16- and 32-bit immediate data can be relocated but smaller fields cannot. 


(abs_exp,An) Operand 


The operand (abs_exp,An) is resolved as Address Register Indirect with 16-bit 
Displacement Mode, provided the expression fits in 16 bits (sign-extended) and 
does not have an explicit .W or .L size code. An absolute extemal expression is 
considered to fit in 16 bits. The abs_exp is used as the displacement. 


If the expression does not fit in 16 bits or an explicit .W or .L is attached to it, the 
68020 Address Register Indirect with Base Displacement and Index Mode is used. 
The specified A register is used as the Base Register, and the Index Register is null. 


As a special case, (0,Am) generates the more efficient Address Register Indirect 
Mode despite the explicit zero displacement. To generate an explicit zero 
displacement, you must use an external symbol. 


(Dn), (Rin.W), (Rn.L), (abs_exp,Dn), 
(abs_exp,Rn.W), and (abs_exp,Rn.L) Operands 


The operands (Dn), (Rn.W), (Rn.L), (abs_exp,Dn), (abs_exp,Rn.W) and 
(abs_exp,Rn.L) generate the 68020 Address Register Indirect with Base 
Displacement and Index Mode. The specified register is used as the Base Register 
if it is an A register without a size code or scale factor attached and as the Index 
Register in all other cases. 


(abs_exp,An,Rn{.W,.L}) and (An,Rn{.W,.L})} Operands 


The operands (abs_exp,An,Rn{.W,.L}) and (An,Rn{.W,.L}) result in the Address 
Register Indirect with 8-bit Displacement and Index Mode provided the abs_exp 
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fits in 8 bits sign-extended. If the abs_exp is absent, a displacement of 0 which fits 
in 8 bits is used. The first A register without a size code or scale factor which is 
encountered, reading left to right, is the Address Register and the other register is 
the Index Register. 


If the abs_exp does not fit in 8 bits, the 68020 Address Register Indirect with Base 
Displacement and Index Mode is used. As before, the first A register without a size 
code or scale factor which is encountered, reading left to right, is the Base Register 
and the other register is the Index Register. Absolute external expressions are 
assumed not to fit in 8 bits. 


Square Brackets and No PC or ZPC 


Any operand containing square brackets but not containing PC or ZPC generates 
one of the 68020 modes: Memory Indirect Post-Indexed or Memory Indirect Pre- 
Indexed. If a register (particularly, an Index Register) is specified outside the square 
brackets, then the Post-Indexed Mode is chosen; otherwise, Pre-Indexed Mode is 
chosen. Any registers and displacements not specified are null. Any relocatable 
displacements are assumed to be 16 bits unless specified to be 32 bits by attaching 
-L. 


(rel_exp,Rn{.W,.L}) Operand 


The operand (rel_exp,Rn{.W,.L}) results in Program Counter Indirect with 8-bit 
Displacement and Index Mode provided the rel_exp is known to be in the same 
section as the instruction. The specified register is used as an index register. The .L 
qualifier on the register indicates all 32 bits of it are to be used. The .W or no 
qualifier indicates the low order 16 bits are to be used, sign-extended. The 
displacement is calculated by subtracting the current PC from the re/_exp; this 
value must fit in 8 bits sign-extended or an error occurs. 


If the rel_exp is not in the same section as the instruction, the Address Register 
Indirect with Base Displacement and Index Mode is used. The specified register is 
used as a Base Register if it is An and otherwise as the Index Register. 


(rel_exp,An,Rn{.W,.L}) Operand. 


The operand (re!_exp,An,Rn{.W,.L}) generates the Address Register Indirect with 
Base Displacement and Index Mode. The first A register without a size code or 
scale factor which is encountered, reading left to right, is the Base Register and the 
other register is the Index Register. Relocatable displacements are assumed to 
require 16 bits unless specified otherwise. 


The operands (rel_exp,Dn,Rn{.W,.L}) and (Dn,Rn{.W,.L}) are invalid. One of the 
two registers must be an A register or PC. 
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(exp,PC) Operand 


The operand (exp,PC) results in Program Counter Indirect with 16-bit 
Displacement Mode provided the displacement (not the actual specified exp) fits in 
16 bits sign-extended. As noted above, when exp is absolute, it is by default a 
displacement, not an address, so in this case no further calculation needs to be done. 
The OPT ABSPCADD option overrides this default. 


If a displacement needs to be calculated, the following rules are followed: 


1. When the operand is in the same section as the instruction, the 
displacement is calculated to be the value of the exp minus the current value 
in the program counter (not the location counter). 


2. When the operand is not in the same section as the instruction but is 
elsewhere in the current module, the value used for calculating the 
displacement is the offset of the operand from the beginning of its section, 
and the displacement is resolved finally by the linker. 


3. When the operand is an external reference, the value used for calculating 
the displacement is 0 and the displacement is resolved finally by the linker. 


- If the assembly-time displacement, as determined from the rules above, does not fit 


in 16 bits sign-extended, the assembler chooses the Program Counter Indirect with 
Base Displacement and Index Mode with a null index register and 32-bit 
displacement field. It is possible for errors to occur at link time if the final 16-bit 
displacement calculated by the linker does not fit in its field. 


(exp,PC,Rn{.W,.L}) Operand 


The operand (exp,PC,Rn{.W,.L}) results in Program Counter Indirect with 8-dit 
Displacement and Index Mode provided the displacement (as determined by the 
rules discussed above) fits in 8 bits sign-extended and does not require relocation 
by the linker, The latter condition means the operand must be in the same section as 
the instruction and cannot be external. In any other case, the operand results in the 
Program Counter Indirect with Base Displacement and Index Mode with a null 
index register. The size of the displacement field is 16 bits, unless 32 bits are to be 
required for the assembly-time displacement or an explicit .L is appended to the 
exp. 


The operands (exp,Dn,Rn{.W,.L}) and (Dn,Rn{.W,.L}) are invalid. One of the two 
registers must be an A register or PC. 
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Square Brackets and PC or ZPC 


Any operand including square brackets with either PC or ZPC is resolved to one of 
the Program Counter Memory Indirect Post-Indexed or Program Counter Memory 
Indirect Pre-Indexed Mode. The PC or ZPC in either case must be inside the square 
brackets. 


Program Counter Memory Indirect Post-Indexed Mode is chosen if there is an 
Index Register specified outside the square brackets; otherwise, Program Counter 
Memory Indirect Pre-Indexed Mode is chosen. 


If the specified mnemonic were PC, the displacement would be determined as in 
the preceding 2 paragraphs, but if the mnemonic was ZPC, the specified exp for the 
base displacement if any is always the displacement itself, which never has the PC 
contents subtracted from it. Note that in the ZPC case, the PC will not be added in 
at run-time to create the effective address. 


Addressing Mode Selection 


The assembler’s rules for choosing an addressing mode for expression types are 
summarized in the following sections. Note that: 


1. These rules do not apply to the Bee or DBcc instructions, which always use 
Program Counter plus Displacement modes. 


2. The final choice between addressing modes Absolute Short Address and 
Absolute Long Address is determined by the .S or .L qualifier on the JMP 
and JSR instructions. These qualifiers will not cause an absolute mode to be 
used instead of the Program Counter Indirect with 16-bit Displacement 
Mode, nor will they cause a reference to a location that is known to be in 
short-addressable memory to use Absolute Long mode. 


ABS Section 


abs_exp 


The rules for determining an addressing mode for expression types for an ABS 
instruction section are listed in the following subsections. 


If OPT P is set and the displacement is within a 16-bit range, then the Program 
Counter Indirect with 16-bit Displacement Mode is used. 


If OPT P is not set or the displacement is not within a 16-bit range, then Absolute 
Short Address Mode is used if the operand is in short-addressable memory; 
otherwise, Absolute Long Address Mode is used. 
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External Reference In Specified Section 


If the section of the operand is short, then Absolute Short Address Mode is used; 
otherwise, Absolute Long Address Mode is used. 


External Reference in Unspecified Section 


If the operand was defined in XREF.S or if OPT F is set, then Absolute Short 
Address Mode is used; otherwise, Absolute Long Address Mode is used. 


rel_exp 


If the section of the operand is short, then Absolute Short Address Mode is used; 
otherwise, Absolute Long Address Mode is used. 


unknown forward ref 


If OPT F is set, then two bytes are allocated; otherwise, four bytes are allocated, 


REL Section 


The rules for determining an addressing mode for expression types for an REL 
instruction section are listed in the following subsections. 


abs_exp 


If the operand is in short-addressable memory, then Absolute Short Address Mode 
is used; otherwise, Absolute Long Address Mode is used. 


External Reference In Specified Section 


If OPT R is set then the Program Counter Indirect with 16-bit Displacement Mode 
is used; otherwise, the Absolute Short Address Mode is used if the section of the 
operand is short and the Absolute Long Address Mode is used if it is not. 


External Reference in Unspecified Section 


If the operand was defined in XREF.S or if OPT F is set, then Absolute Short 
Address Mode is used; otherwise, Absolute Long Address Mode is used. 


rel_exp 
If OPT R is set, then the Absolute Long Address Mode is used. 


If OPT R is not set, the operand and instruction are in the same section, and the 
displacement is within a 16-bit range, then the Program Counter Indirect with 16- 
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bit Displacement Mode is used; otherwise, Absolute Short Address Mode is used if 
the operand is in short-addressable memory and Absolute Long Address Mode is 
used if it is not. 


unknown forward ref 


If OPT F is set, then two bytes are allocated; otherwise, four bytes are allocated. 


User Control of Addressing Modes 


The default addressing mode using ASM68K is Absolute Long Mode (in all cases 
except those where it is known that a more compact mode will work). Since this 
mode generates the longest machine codes (requiring 4 bytes of extension), you will 
want to choose a more compact and faster mode in some cases. 


The choice of mode can be controlled in several ways: 


1, 
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Relocatable sections or external references can be specified as short (see 
Chapter 5, Relocation, for further information), meaning that any references 
to those sections and external references will use Absolute Short Mode in 
preference to Absolute Long Mode (but not in preference to other modes). 
Short sections and external references are always placed in the short- 
addressable areas of memory by the linker. 


. The option flag P can be set with the OPT directive, causing all references 


to a known absolute location from an absolute location to use Program 
Counter Indirect with 16-bit Displacement Mode provided the displacement 
is within 16-bit range. — 


. The option flag R can be set with the OPT directive, which causes all 


references from a relocatable location to a relocatable location (including 
external locations known to be in a relocatable section because the section 
name was specified on the XREF directive) to use Program Counter 
Indirect with 16-bit Displacement mode. Most such references must be 
resolved by the linker. 


This option requires careful use because those locations that are not within 
16-bit displacement from the current PC will cause errors, either in the 
assembler or in the linker. These errors will not happen if the default 
Absolute Long Mode is used. 


. The option flag F can be set with the OPT directive, causing all forward 


references except those in relative branch instructions (Bcc) to allocate only 
2 bytes for the extension rather than the default of 4 bytes. 
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This option requires careful use since it is possible that a location can only 
be addressed by Absolute Long Mode in which case there will not be room 
for the address and an error will result. With the default setting, however, 
even if 4 bytes are allocated, a 2-byte addressing mode can be selected in 
which case the final 2 bytes will be filled with a NOP. 


. The option flag B can be set with the OPT directive, which applies only to 


the relative branch instructions (Bcc) and causes forward references in one 
of these instructions to use the shorter form of the instruction, with 8-bit 
displacement. Possibly, there may not be room for the actual displacement, 
and unnecessary errors could occur. 


. Individual Bcc, JMP and JSR instructions can apply the .S or .L qualifiers 


to the opcode in order to force the use of the short or long form of the 
instruction. In the Bee instructions, use of these qualifiers forces the 
appropriate form. In the JMP and JSR instructions, use of these qualifiers 
does not force an absolute addressing mode to be chosen in those cases 
where a PC with displacement is known to work. However, if an absolute 
mode is used, the qualifier will force the choice of short or long, unless the 
reference is known to exist in short-addressable memory. 


A Bcec.S instruction cannot reference the next statement since this would 
result in an 8-bit displacement of 0, causing the hardware to take the 
following word as the 16-bit displacement rather than as an instruction. 
Also, a Bce.S cannot reference an external reference or any location outside 
the instruction section since the linker cannot resolve 8-bit displacements. 


A2-A5 Relative Addressing 


In the context of using ASM68K with Microtec Research C, Pascal, and 

. FORTRAN compilers, A2-A5 relative addressing refers to the method of accessing 
memory locations relative to an address in an address register as opposed to the 
program counter or via absolute addresses. A2-A5 relative addressing is associated 
with the address register indirect with displacement addressing modes and the 
INDEX linker command. 


ASM68K does not restrict the use of relative addressing with AO, Al, A6, and A7. 
Rather it supports the compiler run-time requirements for An-relative data access. 


A2-AS relative addressing is useful when: 


e Accessing statically allocated data areas. This is as efficient as using the 
absolute short addressing mode with the additional benefit of being able 
to locate the data area (up to 64K bytes long) anywhere in memary. 
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e Accessing dynamically allocated data areas which are independent of 
the code that accesses them. 


Address Register Indirect with Displacement Modes 


The address register indirect with displacement addressing modes are generated by 
operand syntaxes such as exp(An) or (exp,An,Rn), etc. If possible, the 
displacements are calculated by the assembler when exp is an absolute expression 
or by the linker when exp is a relocatable expression. 


Absolute Expressions versus Relocatable Expressions 


When assembly language operands combine absolute expressions with address 
register indirection, the absolute expression is actually the displacement to be 
included with the instruction code. 


When assembly language operands combine relocatable expressions with address 
register indirection (for example, rel_exp(An) or (rel_exp,An)), the syntax says to 
access the location of the relocatable expression indirectly, using the address 
register. In other words, the relocatable expression is the effective address. When 
relocatable expressions are combined with address register indirection, the linker 
will calculate the displacements with the following equations: 


effective_address= An + displacement 
displacement = effective_address - An 
displacement = relocatable_expression - An 


The linker knows the value of the relocatable expression; however, it does not know 
what will be in An when the expression executes. 


To solve the linker’s problem of not knowing the nin-time contents of an address 
register and to let you use relocatable expressions in conjunction with the powerful 
address register indirect with displacement modes, the linker INDEX command 
was created to let you specify the run-time value of An. 


The INDEX Linker Command 


The INDEX command lets you equate the run-time value of an address register 
(AZ, A3, A4, or AS) with the load address of a relocatable section and an offset. The 
INDEX command will also create a public symbol in the form 7An (where n = 2, 
3, 4, or 5). The public symbol created can be declared as an extemal symbol in the 
assembly language source file (with the XREF directive) and used to initialize the 
appropriate address register. 
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When the INDEX command is not used, the linker will still calculate displacements 
for operands which combine relocatable expressions and address register 
indirection; however, the linker considers the run-time value of Az to be zero. 


Accessing Statically Allocated Areas 


The 68000/20 address register indirect with displacement addressing modes (for 
example, those modes generated for syntaxes such as exp(An) or (exp,(An,Rn), 
etc.) are often the fastest and most efficient ways to access code or data locations. 
This is especially true when accessing code or data in high memory where the 
alternative would be to use absolute long addressing as shown in Figure 4-1. Notice 
that the address register indirect mode is coded in two fewer bytes than the absolute 
long mode. 


The address register indirect mode is useful because you can access locations 
anywhere in memory with the same number of bytes of code generated. With a 
signed 16-bit displacement, you can also access up to 64K bytes (+/- 32K) relative 
to the contents of the address register. 
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Microtec Research ASMG8K Version 6.6 Sun Aug 25 12:18:29 1994 Page 1 


Command 


line: asm6Bk -) TEST1 


Line 4ddress 


BON MOMAWNE 


DATA 


eacessas i 
eeeanad2 QFFFEH 


; Address Mode Generated 
CODE 


 $eReB8G8 3839 BGB6 BBee R YORDi,06 ; Absolute lang 
BB268B86 362A 8098 R WORD1(A2),D@ ; Address Reg. Indirect 


with Displacement 


Microtec Research ASMBBK Version 6.8 Sun Aug 25 12:18:29 1991 Page 2 


Label 
WORDi 


Microtec Research, Inc. 


Symbol Table 
Value 


DATA: ee08080 


Figure 4-1. Absolute versus Indirect Addressing Nodes 
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Accessing Dynamically Allocated Areas 


Dynamic memory allocation routines typically pass the size of some element for 
which memory is to be allocated and return the address of the data area which has 
been allocated (a pointer to the allocated block of memory). At link time, the linker 
does not know what the address of the dynamically allocated area will be, but it does 
know the kind of element for which memory is allocated. With this knowledge and 
with the help of the INDEX command, displacements can be calculated for A2-A5 
relative addressing instructions. At runtime, the address of the dynamically 
allocated area is placed in the appropriate address register, and the dynamically 
allocated area can be accessed with A2-A5 relative addressing. 


Example Listings 
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The following listings provide examples of A2-AS relative addressing and how to 
use the INDEX command. The assembled source file output listing is shown in 
Figure 4-2. The linker map file in Figure 4-3 shows the INDEX command used with 
an offset. The linker map file in Figure 4-4 shows the INDEX command used 
without an offset. Comments are included in the assembly source file and in the 
linker command files to explain the instructions and commands. 
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ss Example 1: 


Micratec Research ASM68K Version 6.6 Sun Aug 25 12:92:28 1991 Page 1 


Command line: asm68k -1 TEST2 
Line Address 


; This symbol is defined by 
; the linker INQEX command. 


; To get the effective address 
j on the linker listing. 


anaeeees 

eaBaseea Effective address of VAR = 
3 load address of DATA section 
3; + B@BGH. 


SECT PROG 
eapaeeee 247C Beee BABB E MOVE.L #742,A2 5 Initialize A2 with run-time 
3 value specified in the INDEX 
3 command. 


@ae8a886 426A 6B00 CLR VAR(A2) ; Address Register Indirect 
; with Displacement mode 
; is generated. When this 
; module is linked, linker 
; will calculate the 16-bit 
(> ; displacement of A2 (as 
; Specified by the INDEX 
3 command) fram the 
; effective address of VAR. 


Figure 4-2. A2-A5 Relative Addressing Example 


C) 
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Symbol Table 
Label Value 


i? ¥4 External 
VAR DATA: Bage6eaE 


Figure 4-2. A2-AS Relative Addressing Exampie (cont.) 


4-24 Microtec Research, Inc. 


Addressing Modes A2-A5 Relative Addressing 


Example 2: 


Microtec Research LNK68K Version 6.8 Sat Aug 94 18:25:25 1991 Page 1 


Command line: ink68k -mc TESTS.opt 


LIST C+; Inciude a cross reference 
3 table on the output listing. 


INDEX 2A2,DATA,8@8GH The run-time value of AZ equals the 
ljoad address of the DATA section 
plus an offset of 8800H (this allows 
16-bit signed displacements to access 
+/~- 32K bytes relative to AZ). 


SECT DATA=@FF@BBBK ; Run-time value of AZ = GFF@BBGH + BBBGH, 
; = GFFSBBBH. 

The displacement calculated for the "CLR VAR(A2)" instruction 

1s the effective address of VAR (@FF@886 + GEQGH) minus tha 

run-time value of AZ (@FFE@@GH): 


Displacement = GFFG@Q8H - BFFB@ABH = -2888H = GEBBBH. 
&t run-time, the “MOVE.L #7A2,42" instruction initializes A2 


with GFFEBBBH. The "CLR VAR(A2)" instruction clears the 
location indexed by A2 plus the displacement, which equals: 


2 
a 
® 
a 
* 
” 
™ 
* 
2 
2 
s 


GFFS@BGH + GEBBGK = GFFERGAH + (-26@BH) = BFFEBREH. 


( 5 SECT PROG=1000H 
. LOAD TEST2 
ae END 


Figure 4-3. Using the INDEX Command with Offset 


@ 
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OUTPUT MODULE NAME: TEST3 
OUTPUT MODULE FORMAT: IEEE 


SECTION SUMMARY 


SECTION ATTRIBUTE . START END LENGTH ALIGN 


PROG NORMAL CODE @ae81e00 gae1ee9 BeaeRevA 2 (WORD) 
DATA NORMAL DATA Q@aFFag@s G@OFFFFFE @@eFFFF 2 (WORD) 


MODULE SUMMARY 
MODULE SECTION: START SECTION:END FILE 


TEST2 DATA: BBFFEBBE DATA: OBFFFFFE /tast/TEST2.0 
PROG: 80881888 PROG: 8081809 


CROSS REFERENCE TABLE 


SECTION ADDRESS MODULE ey. 
DATA eerFFEeBa  -TEST2 
aeFFaeea = - $$ 
TEST2 


START ADDRESS: 99880800 


Load Completed 


Figure 4-3. Using the INDEX Command with Offset (cont.) 
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Microtec Research LNKEBX Version 6.8 Sat Aug 3i 18:32:81 1991 Page 1 


Command line: Ink68k -mc TEST4.opt 


LIST C ; Include a cross reference table on tha output 
3 listing. 


INDEX 742,DATA,@ 5; The run-time value of A2 equals the 
} load address of the DATA section. 


SECT DATA=@FF@8@BH ; Run-time value of 42 = OFFOBEBH. 


The displacement calculated for the "CLR VAR(A2)" 
instruction is the effective address of VAR (BFF8@QB + 
688GH) minus the run-time value of A2 (@FFQBGGH): 


Displacement = BFFE@8GH - BFF@BBBK = GEAR. 


4t run-time, the "MOVE.L #7A2,A2" instruction initializes 
A2 with @FF@GGQH. The “CLR VAR(A2)" instruction clears 
the location indexed by 42 plus the displacement, which 
equals: 

GFFGGGOH + BABGH = BFFEGSGH. 


5 
x 
Sd 
* 
* 
. 
= 
s 
s 
sd 
* 


SECT PROG=18@@H 
LOAD TEST2 
END 


: CO 


Figure 4-4. Using the INDEX Command without Offset 
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QUTPUT MODULE NAME: 
OUTPLT MODULE FORMAT: 


Addressing Modes 


Sat Aug 31 18:92:81 1991 


Version 6.6 Page 2 


TEST4 
TEEE 


SECTION SUMMARY 


SECTION 


PROG 
DATA 


START END 


o9981869 
BOFFFFFE 


ATTRIBUTE LENGTH ALIGN 
GeeseasA 


@BQ6FFFF 


NORMAL CODE 
NORMAL DATA 


68861868 
@aFFeaea 


MODULE SUMMARY 


MOOULE 
TEST2 


SECTION: START SECTION: END FILE 
DATA:@8FFFFFE /test/TEST2.0 


PROG : 482901849 


DATA: @@FFaage 
PROG : 48881888 


CROSS REFERENCE TABLE 


START ADDRESS: 


SECTION ADORESS MODULE 


DATA @BFFeene 


6aFFae88 


-TEST2 
-$3 
TEST2 


eeaeneea 


Load Compteted 
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Figure 4-4. Using the INDEX Command without Offset (cont.) 


2 (WORD) 
2 (WORD) 
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Introduction 


Object modules produced by ASM68K are in a relocatable format which lets you 
write modular programs whose final addresses will be adjusted by the LNK68K 
Linker. Individual program modules can be changed without reassembling the 
entire program, and separate object modules can be linked together into a final 


program. 
Relocatable programming provides the following advantages: 


¢ Actual memory addresses are of no concer until final link time. 
¢ Large programs can be easily separated into smaller modules, developed 
separately, and linked together. 
e If one module contains an error, only that module needs to be modified 
: and reassembled. 
* Once developed, a library of routines can be used by many people. 
* The linker will adjust addresses to meet program requirements. 


Program Sections 


To take advantage of relocatability, you should understand the concept of program 
sections and how separate object modules are linked together. A program section is 
that part of a program which contains its own location counter and is logically 
distinct from other sections. At link time, the addresses for each section can be 
specified separately. 


Sections are identified by names that follow the syntactic mules for symbols. Section 
names can duplicate labels or register names without conflict; they can be any 
symbol or a two-digit decimal number. Section names can appear in COMMON, 
SECT (or SECTION), and KREF directives as well as in the SEZEOF. and 
STARTOF. operators. 


ASM68K provides for up to 200 program sections including both numbered and 
named sections. LNK68K can link up to 32,767 sections. One of these is predefined 
to be 00 (numbered section 0). Each relocatable section has four attributes: 

* common/noncommon 

e short/long 

e section type 

e section alignment 
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Common versus Noncommon Attributes 


A section becomes common when its name appears ina COMMON directive, and 
becomes noncommon when its name appears in a SECT or SECTION directive. It 
is a fatal error for the same section name to appear in both directives. The linker 
loads all common sections with the same name (from different modules) into the 
same place in memory while noncommon sections with the same name (from 
different modules) are concatenated, Otherwise, common and noncommon sections 
are treated alike. 


You should avoid putting instructions or code-generating directives (DC, DCB) in 
common sections. If you initialize the same common section in two different 
modules, both sets of code will be loaded into the same memory locations by the 
linker, which does not report this occurrence as an error. This can obviously cause 
problems. On the other hand, initializing a common section in only one module can 
be useful. The assembler gives a W flag (warning) whenever it sees bytes generated 
in a common section. 


In a given assembly, a section name can appear in an XREF directive before 
appearing in either a SECT (or SECTION) or COMMON directive. When this 
occurs, the assembler accepts the name as a valid new section name and assigns the 
long or short attribute to it as declared in the XREF directive, but does not yet 


assign the common or noncommon attribute to it, 


The common or noncommon attribute can be set by the subsequent occurrence of a 
SECT or COMMON directive that uses the same section name. However, if the 
current assembly does not assign the common/noncommon attribute, the linker can 
do so. In this instance, the section name must appear in a SECT or COMMON 
directive in another assembly; one whose object module is included in the link. 


For more information on these attributes, refer to Relocatable Sections in Chapter 
10, Linker Operation. 


Short versus Long Attributes 


5-2 


A section becomes short when its name appears in a COMMONS, SECTS, 
SECTIONS, or XREF-S directive. It becomes long when its name appears in any 
of these directives without the .S extension. If a section is short in one place and 
long in another place, a warning is produced and the section is designated as short 
thereafter. The linker will load all short sections into the areas of memory 
addressable with 16-bit absolute addresses. 


In certain situations, the assembler will choose a more compact addressing mode 


when a reference is made to a short section (see Chapter 4 for more information). 
Otherwise, short and long sections are treated alike. 
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For more information on these attributes, refer to Relocatable Sections in Chapter 
10, Linker Operation. 


Section Alignment Attribute 


The section alignment attribute affects the beginning address of each file’s 
contribution to a section. That is, if several files each define a relocatable section A, 
then the beginning address of each section A in each file will be rounded up to the 


specified alignment boundary. 


The section alignment attribute may be either 1, 2 or 4. The default alignment of a 
section is 2 if the linker CHIP command does not specify a 68020, 68030, or 68040 
target microprocessor. 


A section alignment attribute of 4 combined with the ALIGN 4 directive can ensure 
that data items are located at longword boundaries, which may speed execution on 
some target systems where the memory bus is 32 bits wide. 


The alignment attribute is specified in the SECTION assembler directive as shown 
in the following example: 
SECTION A, 4 
If you have specified the alignment attribute differently in several files, the 
= : following rules apply: 
¢ If you have specified an ALIGN linker command for a section, all 


relocatable subsections of that section are aligned modulo the greater of 
the two alignments. 


© If there is no ALIGN linker command, each file’s contribution to a 
section can have a different alignment attribute as specified in the file. 
However, if an alignment attribute of 4 is specified anywhere for a 
section, the first file which contributes to the section is aligned modulo 
4, taking precedence over any alignment attributes in that first file. 


For more information on these attributes, refer to Relocatable Sections in Chapter 
10, Linker Operation. 


Section Type Attributes 


There are four types of relocatable sections: 
1. C— Program Code 
2. D— Data 
3. M — Mixed code and data 
4. R— ROMable Data 


(> 
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The SECTION assembler directive lets you explicitly specify a section’s type by 
adding a C, D, M, or R qualifier to the SECTION directive as described in 
Chapter 6, Assembler Directives. 


The section type attribute serves as documentation to remind you of what a section 
contains. Program code sections generally contain instructions. Data sections 
generally contain read/write data items. ROMable data sections generally contain 
read-only data items. 


The section type attribute affects the production of HP 64000 symbolic information 
in the asmb_sym (assembler symbol) and link_sym (linker symbol) files. The HP 
64000 file formats define three relocatable sections, PROG, DATA, and COMN 
as well as the absolute section(s) ABS. The section type attribute is used to map the 
various relocatable and absolute sections onto the HP 64000 sections PROG, 
DATA, COMN, and ABS. 


You can specify the section type attribute explicitly in the SECTION directive. 
Example: 
SECTION A,,C ;Specifies a CODE section 


If you do not explicitly specify the section type attribute, the assembler assigns the 
section type according to the following rules after encountering the SECTION 
directive: 


1. If the assembler encounters instructions only, the assembler will set the 
section type attribute to program code (C). 


2. If the assembler encounters a data definition directives only, the assembler 
will set the section type attribute to data (D). 


3. If both instructions and data definition directions are encountered, the 
assembler will set the section type attribute to mixed (M). 


For more information on these attributes, refer to Relocatable Sections in Chapter 
10, Linker Operation. 
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Section Types and HP 64000 Symbolic Files 


The HP 64000 symbolic files asmb_sym and link_sym supply program symbol 
information to HP 64000 emulators and analysis tools. For more information on 
these files, see Appendix A, HP 64000 Development System Support, in your 
ASM68K User's Guide. 


When producing HP 64000 symbol files, the symbols from the various sections are 
mapped onto the HP 64000 sections as shown in Table 5-1. 


Table 5-1. ASM68K/HP 64000 Section Mapping 


ASM68K Section HP 64000 Section 


C (program code) PROG 

D (data) DATA 
R (ROMabie data) COMN 
Extra (code, data, and ROMable data) 


ORG (absolute) 


The HP 64000 assembler symbol and linker symbol file formats have the following 
characteristics: 


¢ The file formats allow a maximum of three relocatable sections per 
assembly source file. For each assembly, one section maximum can be 
mapped to PROG, one section to DATA, and one to COMN. 


¢ The file formats allow an unlimited number of absolute sections per 
assembly source file. 


If the assembler, through any combination of SECTION directives, attempts to 
map more than one section onto PROG, DATA, or COMN using the rules shown 
in Table 5-2, this mapping conflicts with the HP 64000 file formats. The assembler 
and linker then do the following: 


1. The second and subsequent sections that map to either PROG, DATA, or 
COMN are called extra CODE, DATA, and ROM sections 


2. The symbols from extra sections are omitted from the HP 64000 assembler 
symbol file, which means that local symbols from extra sections will not be 
available at assembler analysis-time. When this happens, the assembler 
issues the following warning: 


WARNING: (604) Maximum number of typed sections exceeded in 
HP mode. 
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3. The code from the extra section is correct and is treated normally 


4. The linker, when producing a link_sym file, maps the symbols from extra 
sections to HP 64000 ABS sections. The symbol values are correct. They 
appear as ABS on HP emulators and analysis tools. 


Because the assembler allows many relocatable sections, it is sometimes impossible 
to produce perfect HP 64000 assembler symbol and linker symbol files. In these 
situations, the code is correct. At worst, you will not have access to some local 
symbols in some assembly files. You can overcome these limitations by moving 
extra sections to a different source file. 


Other Things to Know About Sections 


Typically, a section will contain either instructions or data which lets you place the 
sections in a RAM/ROM environment. Common sections are generally used for 
program variables that reside in RAM. Common sections are similar to named 
COMMON in FORTRAN. As with non-relocatable assemblers, you can also 
specify absolute addresses when assembling a program. In this case, the object 
modules, even if in relocatable format, will contain instructions or data that will 
reside in the specified memory locations. . 


How the Assembler Assigns Section Attributes 


Table 5-2 illustrates how a section is assigned the common/noncommon and short/ 
long attributes. An example of how to use this table follows: 


The first time a section name appears, it has no previous attributes; therefore, the 
first horizontal row of the table is marked undefined. If the name first appears in an 
XREF.S statement, it will afterwards be short, but neither common nor 
noncommon (XREF-only). If the name later appears for a second time in a SECT 
statement, it is then assigned the noncommon attribute as well and a warning is 
produced. 
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Basie Table 5-2. How the Assembler Assigns Section Attributes 
Previous New Statement In Which the Section Name Appears 
Section 
Attribute — XREF XREF.S SECT SECT.S COMMON 
UNDEFINED XREF-ONLY XREF-ONLY NONCOMMON NONCOMMON 
LONG SHORT LONG SHORT 
XREF-ONLY  XREF-ONLY XREF-ONLY* NONCOMMON NONCOMMON" 
LONG LONG SHORT LONG SHORT 
XREF-ONLY | XREF-ONLY* XREF-ONLY NONCOMMON* NONCOMMON 
3 SHORT SHORT SHORT SHORT SHORT 
COMMON COMMON COMMON’ 
LONG LONG SHORT ERROR ERROR 
COMMON COMMON' COMMON 
SHORT SHORT SHORT ERROR ERROR 
NONCOMMON NONCOMMON NONCOMMON* NONCOMMON NONCOMMONT 
LONG LONG SHORT LONG SHORT 
NONGOMMON NONCOMMON* NONCOMMON NONCOMMON’ NONCOMMON 
() SHORT SHORT SHORT SHORT SHORT 


* A wating message is produced. 


Linking 


The object modules produced by the assembler are combined or linked together by 
a linker. The linker converts all relocatable addresses into absolute addresses and 
resolves references from one module to another. Linkage between modules is 
provided by external definitions (XDEF), external references (XREF), as well as 
the common sections. External definitions are defined in other object modules by 
the linker. External references are symbols referenced in one module but defined in 
another module. The linker combines the external definitions from one program 
with the external references from other programs to obtain the final addresses. A 
program can contain both external references and definitions. 


CO) 
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Relocatable versus Absolute Symbols 


Each symbol in the assembler has an associated symbol type, which marks the 
symbol as absolute or relocatable. If relocatable, the type also indicates the section 
to which the symbol belongs. Symbols whose values are not dependent upon 
program origin are absolute, and those whose values change when the program 
origin is changed are called relocatable. Absolute and relocatable symbols can both 
appear in an absolute or in a relocatable program section. 


Absolute symbols are defined as follows: 
e Any symbol in the label field of an instruction that is in an absolute 
section of code. 


¢ A symbol is made equal to an absolute expression by the EQU or SET 
directive. This occurs even if the program is assembling a relocatable 
section. 


e An extemal reference with no section attached is considered to be 
absolute for the purpose of determining addressing modes. 
Relocatable symbols are defined as follows: 
e Any symbol in the label field of an instruction when the program is 
assembling a relocatable section. 


¢ Asymbol is made equal to a relocatable expression by the EQU or SET 
directives. 


¢ An external reference with a section attached is relocatable. 


¢ A reference to the location counter (*) while assembling a relocatable 
section is relocatable. 


Relocatable Expressions 


The relocatability of an expression is determined by the relocation of the symbols 
that compose the expression. Expressions containing undefined or external symbols 
are relocatable. All numeric constants are considered absolute. Relocatable 
expressions can be combined to produce an absolute expression, a relocatable 
expression or, in certain instances, a complex relocatable expression. The following 
list shows those expressions whose result is relocatable. ABS denotes an absolute 
symbol, constant, or expression, and REL denotes a relocatable symbol or 
expression. 


ABS+REL REL+ABS REL-ABS REL+REL REL-REL 
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Complex relocatable expressions are not legal for use with the ORG, OFFSET, 
COMLINE, END, FAIL, SPC, and LLEN directives. 


Complex relocatable expressions result when two relocatable expressions are 
subtracted or added together. Only the plus (+) and minus (-) operators are allowed 
within these subexpressions. In certain instances, subexpressions can evaluate to an 
absolute value. This can occur in cases where a subexpression comprises the 
difference between two relocatable symbols. 


After assembly has been completed, one of three types of expressions result: 


Absolute expression The expression evaluates to an 
absolute value independent of any 
relocatable section addresses. 


Simple relocatable expression The expression evaluates to an 
absolute offset from a_ single 
relocatable section address. 


Complex relocatable expression The expression evaluates to a 

constant absolute offset from either 

a single, negated start address of a 

: relocatable section or references to 

C™ the start addresses of two or more 
relocatable sections. 


In addition, the following valid expressions produce an absolute expression. Both 
relocatable subexpressions must be relocatable in the same program section and 
must be defined in the current module (no externals). REL denotes a relocatable 


symbol or expression. 
REL=REL REL<REL REL<=REL 
REL<REL REL>=REL REL>REL 
REL-REL REL+REL 


Relocatable symbols that appear in expressions with any other operators cause an 
error (e.g., REL*REL). 


Note 


For information on valid expressions, see the section Expressions 
in Chapter 2, Assembly Language. 
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Introduction 


Assembler directives are written as ordinary statements in the assembler language. 
Rather than being translated into equivalent machine language, they are interpreted 
as commands to the assembler. With these directives, the assembler reserves 
memory space, defines bytes of data, assigns values to symbols, controls the output 
listing, etc. 


This chapter describes all directives (also called Pseudo-Ops) except those 
primarily associated with macro assembly, structured syntax, and array relative 
addressing, which are described in later chapters. 


Assembler Directives 


The notational conventions used to describe the syntax of assembler directives is 
the same as that presented in the preface of this manual. The assembler directives 
in this chapter are organized alphabetically. An alphabetical listing of the assembler 
directives is shown in Table 6-1. 


Table 6-1. Alphabetical Listing of the Assembler Directives 


Directive Function 


ALIGN Specifies Instruction Alignment 
CHIP Specifies Target Microprocessor 
COMLINE Defines Storage 

COMMON Specifies Common Section 

DC Defines Constant Value 

DCB Defines Constant Block 

DS Defines Storage 

ELSEC Conditional Assembly Converse 
END End of Assembly 

ENDC Ends Conditional Assembly 
ENDR Ends Repeat 

EQU Equates a Symbol to an Expression 
FAIL Generates Programmed Error 
FEQU Equates a Symbol! to a Floating Expression 


Specifies Floating-Point Options for Assembly 
Formats Listing 
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Table 6-1. Alphabetical Listing of the Assembler Directives (cont.} ‘oe 


Directive Function 


Specifies Module Name 

Checks if Strings Equal (Conditional Assembly) 
Checks if Symbol Defined (Conditional Assembly) 
Checks if Value Equal to Zero (Conditional Assembly) 
Checks if Value Non-Negative (Conditional Assembly) 
Checks if Value Greater Than Zero (Conditional Assembly) 
Checks if Value Non-Positive (Conditional Assembly) 
Checks if Value Less Than Zero (Conditional Assembly) 
Checks if Strings Not Equal (Conditional Assembly) 
Checks if Symbol Not Defined (Conditional Assembly) 
Conditional Assembly Unequal to Zero Test 

Includes Source File 

Specifies Indefinite Repeat 

Specifies Indefinite Repeat Character 

Generates Assembly Listing 

Sets Length of Line in Assembler Listing 

Assembles for R9M Chip 

Specifies Module Name 

Does Not Create an Output Object Module 

Defines Table of Offsets 

Sets Options for Assembly 

Begins an Absolute Section 

Advances Listing Form to Next Page 

Sets Length of Listing Page 

Defines a Register List 

Specifies Repeat 

Restores Options 

Saves Options 

Specifies Section 

Specifies Section 

Equates a Symbol to an Expression 

Spaces Lines on Listing 

Sets Program Heading 

Specifies Weak External Reference 

Specifies External Definition 

Specifies External Reference 
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rN 
m2 ALIGN — Specifies Instruction Alignment 
Syntax 


ALIGN {1 | 2 | 4} 


Description 
1 Byte alignment (8 bits). 
2 Word alignment (16 bits). 
4 Longword alignment (32 bits). 


The ALIGN directive specifies the modulo number of bytes to which the address 
of the next instruction is to be aligned. 


Note 


It is not recommended that instructions be put in sections with byte 


alignment because you cannot guarantee that the starting address of 
{i an instruction will end up on an even boundary during link time. If 

the starting address does not end up on an even boundary, you will 
have an illegal address. 


Example 


ALIGN 2 


In the example, the address is aligned to word alignment. 


age 
a 
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CHIP — Specifies Target Microprocessor 


Syntax 


CHIP target 


Description 
target Specifies target microprocessor. Valid values are: 68000, 
68008, 68010, CPU32, 68020, 68030, 68040, 68881, or 
68851. 


(default: 68000) 


The CHIP directive specifies the target microprocessor. The differences from the 
assembler’s point of view are as follows: 


1. The 68010 has the additional instructions MOVEC, MOVES, RTD and 
MOVE from CCR. If one of these instructions is encountered when the 
CHIP? is not set to 68010, a warming is generated and the 68010 instruction 
is assembled. 


2. The 68020, unlike the 68010, has the additional instructions BFCHG, 
BFCLR, BFEXTS, BFEXTU, BFFFO, BFINS, BFSET, BFTST, BKPT, 
CALLM, CAS, CAS2, CHK2, CMP2, DIVSL, DIVUL, PACK, RTM, 

+ TDIVS, TDIVU, TRAPcc, Tec, FPcc, and UNPK. It has six new 
addressing modes as described in the 68020 instructions DIVS, DIVU, 
EXTB, LINK, MOVEC, MULS, MULU, and TST. Using any of these 
constructs when the CHIP is not set to 68020, 68030, or 68040 produces an 
error, 


Note that using new Motorola 68020, 68030, or 68040 syntax is not 
sufficient to produce a warning, provided the generated code is 68000- 
compatible. Examples of this include an explicit scale factor on an index 
register, using the EXTB and EXTW synonyms for EXT, placing a 
displacement inside rather than outside the delimiting parentheses, and 
rearranging the order of registers inside parentheses. 


3. The 68030 has the additional instructions PFLUSH, PFLUSHA, 
PLOADR, PLOADW, PMOVE, PMOVEFD, PTESTR, and PTESTW. 
It also has the additional registers CRP, SRP, TC, TTO to TTI, and 
MMUSR. 


4, The 68851 has the additional instructions PBcc, PDBcc, PFLUSH, 


PFLUSHA, PFLUSHS, PFLUSHR, PLOADR, PLOADW, PMOVE, 
PRESTORE, PSAVE, PScc, PTESTR, PTESTW, PTRAPcc, and 
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CHIP 


PVALID. It also has the additional registers VAL, CAL, SCC, CRP, SRP, 
DRP, TC, AC, PCSR, PSR, BAD0 to BAD7, and BAC0 to BACT. 


The CPU32 has the same instructions as the 68010 with the following 
additions: Bcc.L, BGND, BRA.L, BSR.L, CHK.L, CHK2, CMP2, 


DIVS.L, DIVSL, DIVU.L, DIVU, EXTB, LINK.L, LISTOP, MULS.L, _ 


MULU.L, TBLS, TBLSN, TBLU, TBLUN, TRAPcc, TST An, and 
TST #<data>. 


The 68040 has the same instructions as the 68020/30 with the following 
additions: CINVL, CINVP, CINVA, CPUSHA, CPUSHL, CPUSHP, 
MOVE16, PFLUSHAN, and PFLUSHN. 


If no CHIP or OPT P (which has the same function) directive appears, the default 
target processor is 68000. 


Example 


CHIP 68020 
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COMLINE — Specifies Memory Space 

Syntax 
COMLINE 

Description 
n Specifies the number of bytes in memory to be reserved. 
The COMLINE directive in the source code reserves a block of sequential memory 
locations (in bytes). The argument is the specified number of bytes (e.g., 
COMLINE § reserves 8 bytes in memory). 


COMLINE is supplied for Motorola compatibility. ASM68K treats COMLINE as 
a DS.B instruction. 
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nnn 
| Ge. COMMON —- Specifies Common Section 
| Syntax 


(label] COMMON[.S] {sname | snumber}{, [n][,typel (, hptype?) 
Description 


label Specifies the section name. If sname has been specified, 
label will be assigned the address of the current location 
counter (it is a normal label). 


.S Specifies whether the section has the short attribute. 
sname The section name. Any valid section can be used. 


snumber The section number. One or two decimal digits can be used. 
If label is not specified, sniuanber is treated as the name of the 
common section. 


If label is specified, label is appended to snumber to create 

the name of a unique common section, such as 00/abel. This 

common section is not considered to have any particular 

connection with the noncommon (or common) numbered 
( section 0. 


n The number of bytes of alignment. It can be 2 or 4. 
(default = 2) 


type The type of section. It can be: 


D=C(Data 
R ROMable Data 


hptype The HP 64000 section type. It can be: 


A ABS 
D DATA 
c COMN 


The COMMON directive causes the statements following it to be assembled in 
relocatable mode using the named common section. This section remains in effect 
until an ORG, SECT, SECTION, OFFSET, or another COMMON directive is 
assembled that specifies a different section. Initially, all section location counters 
are set to zero. 


You can alternate between various sections within one program by using multiple 
SECT and COMMON directives. The assembler will maintain the current value of 
the location counter for each section. 
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No executable code should be placed in a common section. Therefore, any directive 
that generates code (DC or DCB) and any instruction will be flagged with a warning 
when used in a common section. Typically, the DS directive will be used to allocate 
storage within the common section. 


Note that the same section name or number should not appear in both a COMMON 
and a SECT directive, except where a label is placed on a numbered section to 
create a named common area. 


The Aptype refers to the HP 64000 section type. If it is not specified, ASM68K 
assigns a hptype field according to the following rule: data sections map to DATA 
and ROMable sections map to COMN subject with the following restrictions: 


1. There can be at most one DATA and one COMN section for each module. 


2. The second and subsequent sections assigned to DATA or COMN are 
called extra sections. Extra sections have ABS in their hptype field, and 
their local symbols cannot be written to the HP asmb_symi file. 


You cannot override the first restriction by explicitly assigning more than one 
section to DATA or COMN. If you do so, ASM68K will issue the following 


warning: 
Maximum number of typed sections exceeded in HP mode 


This waming is issued whenever an extra section is created regardless of whether 
the Aptype was set explicitly or implicitly. ; 


If kptype is ABS, the section must be treated as an extra section; that is, the section 
will have no symbols in the asmb_sym file because it is impossible to relocate 
them. 


Example 


LABEL1 COMMON SECT1 ? Name is SECT1, LABELI is 
# normal symbol 
COMMON CODE # Name is CODE 
COMMON 1,4,D  ; Name is 1, common section 
# quad aligned, containing data 
LABEL1 COMMON 1 * Name is 1LABEL1, common section 
; 


No conflict with other LABEL1 
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DC — Defines Constant 
Syntax 


tlabel) Dc{.qualifier) operand(,operand]... 


Description 
label Specifies an optional label that will be assigned the address 
of the first byte defined. 
qualifier Specifies an optional qualifier that can be: 
-B Byte data 
WwW Word data 
.L Longword data 
.S Single precision floating 
-D _— Double precision floating 
Xx Extended floating 
.P Packed binary coded decimal 
The default is .W. 
operand Specifies a character string or an expression for qualifiers .5, 


., and .. All expressions are calculated as 32-bit values. 
For .8, this value must fit in 8 bits (either zero-filled or one- 
filled); for .w, it must fit in 16 bits. If this condition is 
violated, an error is produced. 


Specifies a floating-point number for qualifiers .s, .D, .x, 
and .p. If this number cannot be stored in the indicated 
number of bits (because its exponent is too large), an error is 
teported. However, excessive bits of precision in a specified 
mantissa are truncated without a warning. 


The DC directive defines up to 509 bytes of data. The assembly program counter 
symbol is represented by an asterisk (*). This symbol gets evaluated to be the 
address of the beginning of the DC command plus the number of operands 
preceding the asterisk. Motorola evaluates it at the beginning of the DC command. 


Operands of a DC.W or DC.L can be relocatable while operands of a DC.B are not 
relocatable. Operands of a DC.S, DC.D, DC.X, and DC.P can only be floating- 
point numbers. 


Character strings are stored one character per byte, starting at the lowest-addressed 
byte. Character strings in a DC.W or DC.L are padded out with zeros in the least 
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significant bytes of the last words, if necessary, to bring the total number of bytes 
allocated to a multiple of 2 or 4, respectively. 


If an odd number of bytes is entered in a DC.B directive, the odd byte on the right 
will be skipped and the location counter aligned to an even value, unless the next 
statement is another DC.B, a DS.B, or a DCB.B. The byte skipped over is not 
initialized in any way. 

For operands other than character strings, the assembler will allocate one byte per 
operand for a DC.B, two bytes per operand for a DC.W or DC with no qualifier, 
four bytes per operand for a DC.L or DC.S, and eight bytes per operand for a DC.D. 
The operand must evaluate to a value that fits into the specified number of bytes or 
an error is generated. Negative values are stored using their two’s complement 
representation. 

The .S and .D qualifiers permit definition of single and double precision floating- 
point numbers, respectively. The generated bit pattems are [EEE standard and are 
compatible with the Motorola MC6888 1/MC68882 chip. Single precision is 1 sign 


bit, 8 exponent bits (biased by 127), and 23 mantissa bits. Double precision is 1 sign — 


bit, 11 exponent bits (biased by 1023), and 52 mantissa bits. 


Floating-point numbers can be in either decimal or hexadecimal format. A decimal 
floating-point number must contain either a decimal point or an E indicating the 
beginning of the exponent field. 


Examples 


3.14159 


-22E-100 ; Equivalent to -22 * 10729 


Underscores can occur before or after the £ to increase readability. Underscores are 
ignored in determining the value of a constant. 


A hexadecimal floating-point number is denoted by a colon (:) followed by a series 
of hex digits (up to 8 digits for single precision or 16 digits for double precision). 
The digits specified are placed in the field as they stand. You are responsible for 
determining how a given floating-point number is encoded in hexadecimal digits. 
If fewer digits than the maximum permitted are specified, the ones that are present 
will be left-justified within the field. Thus, the first digits specified always represent 
the sign and exponent bits. 


The DC.S, DC.X, DC.P, and DC.D directives will accept only floating-point 
numbers as operands. DC with any other qualifier will not accept floating-point 
numbers as operands. 
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ad Example (with generated bytes shown) 
Generated Bytes Directive Operand 


4142 4344 4566 DC.B *ABCDEfghi' 
6768 69 

45 pc.B 'E¢ ; starts at odd address 
6500 Dc te! 

4500 0000 Dc.L ‘gE! 

3132 3334 3500 bc.L "12345! 
0000 

OOOA 0005 0007 pC.W 10,5,7 
OOFF oc SFF 

3F80 0000 poe.s 1.0 

3FFO 0000 0000 pc.D 1.0 

6000 

3F80 0000 De.s :3F8 

3FFO 0000 0000 Dc.D- :3FF 

0000 


a 
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DCB — Defines Constant Block 


Syntax 


(label) pcB{.qualifier] length,value 


Description 


label 


qualifier 


length 


value 


Specifies a label that will be assigned the address of the first 
byte allocated. 


Defines the units in which storage is allocated. The units can 
be any of the following: 


.B Bytes 

wW Words 

.L Longwords 

-S Single precision 
.D Double precision 
Xx Extended floating 


.P Packed binary coded decimal 
The default is .w. 


Defines the number of units of storage to allocate. This 
absolute expression cannot contain forward, undefined, or 
extemal references. 


Defines the initial value for each unit. For qualifiers .5, .¥, 
and: .L, this is an expression that can contain forward 
references, relocatables, externals, or complex expressions. 
For qualifiers .s, .p, .x, and .p, this is a floating-point 
number as described under the DC directive. 


The DCB directive causes the assembler to allocate a block of bytes, words, 
longwords, single precision floating-point numbers (32 bits), double precision 
floating-point numbers (64 bits), extended precision floating-point numbers (96 
bits), or packed binary coded decimal (96 bits) depending on the qualifier. 


Each memory unit allocated is set to the value specified in the directive. This 
directive causes the location counter to be aligned to a word boundary, unless the 
-B qualifier is specified. 


Example 


DCB.L 100, SFFFPFFFE 
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DS — Defines Storage 
Syntax 
(label] Ds[.qualifier] size 


Description 


label Specifies a label that will be assigned the address of the first 
byte allocated. 


qualifier Defines the units in which storage is allocated. The units can 
be any of the following: 


.B 


Kobo & 


.P 


Bytes 

Words 

Longwords 

Single precision 

Double precision 

Extended floating 

Packed binary coded decimal 


The default is .W. 


size Specifies the number of units to be allocated by this 
directive. Any symbols used in this expression must be 
previously defined. The final expression cannot contain any 
telocatable terms. 


The DS directive reserves a block of sequential locations of memory. It causes the 
program counter to be advanced and, for this reason, the contents of the reserved 
bytes are unpredictable. Locations can be reserved in units of bytes, words, 
longwords, single precision floating-point numbers (32 bits), double precision 
floating-point numbers (64 bits), extended precision floating-point numbers (96 
bits), or packed binary coded decimal (96 bits). 


The DS directive causes the location counter to be aligned to a word boundary 
untess the .B qualifier is used. The form DS 0 can be used to force alignment 
between two DC.B, DS.B, or DCB.B statements, if necessary. 


Example 


JAKE DS $62 
MOE DS.B 100 


Microtec Research, Inc. 


6-13 


ELSEC Assembler Directives 


ELSEC — Specifies Conditional Assembly Converse 


Syntax 
ELSEC 
Description 


The ELSEC directive is used in conjunction with one of the conditional assembly 
directives (IFNE, IFEQ, IFLT, IFLE, IFGE, IFGT, IFC, or IFNC) and is the 
converse of the conditional assembly directive. When the argument of the 
conditional assembly directive evaluates to false, all statements between the 
ELSEC directive and the next ENDC are assembled. When the argument of the 
conditional assembly directive evaluates to true, no statements between the ELSEC 
directive and the next ENDC are assembled. 


The ELSEC directive is optional and can only appear once within a block of 
conditional assembly statements. 


Example 
IFNE MAIN 
ELSEC 


ENDC 
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C) END — Ends Assembly 
Syntax 
END [expression} 
Description 


expression Specifies an address placed in the end record of the load 
module that informs the linker where program execution is 
to begin. If this expression is not specified, the module is 
considered not to contain a starting address. If no module 
read by the linker contains a starting address, execution 
begins at absolute 0. 


The END directive informs the assembler that the last source statement has been 
read and indicates a load module starting address. Any statements following the 
END directive will not be processed. 


If expression is not present but a comment field is present, the latter must be 
preceded by a semicolon (3) or an exclamation mark (!). 


Specifying a load address in the END directive also informs the linker that this is a 
CY main program. If multiple load modules are combined by the linker, only one 
é module can specify a load address and, for this reason, a main program is indicated. 
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Example 


Command line: asm68k -1 end 
Line Address 


i 
2 
3 
4 
5 
6 
7 
8 00000000 
9 00000050 
10 
11 
12 00001000 6000 0002 
13 00001004 2E7C 0000 1000 
14 
15 
16 00000000 4EB9 0000 0000 E 
17 00000006 227C 0000 0000 R 
18 ooo0e00c 1219 
19 QOO0000F OC01 0014 
20 00000012 67F8 
21 00000014 4EB9 0000 0000 E 
22 OOQOO0IA 4E75 
23 
24 00000014 
25 
Symbol Table 
Label Value 
BLNK 00600014 
ECHO SECT1: 00000050 
INBUF SECT1:00000000 
MAINIO SECT2:0000000C 
MAIN2 SECT2 : 00000000 
PROC 00001004 
READ External 
SCAN External 


MAINI 


PROC 


MAIN2 


MAINLO 


BLNK 


IDNT 


ORG 
MOVE .L 


SECT 
JSR 
MOVE .L 
MOVE .B 
CMP .B 
BEQ 


INBUF, ECHO 
READ, SCAN 


SECT1 
80 
i 


$1000 
PROC 
#$1000, SP 


SECT2 
READ 
#INBUF, Al 
{Al} +,D1 

#BLNK, Di 
MAIN1O 
SCAN 


20 
MAINZ 
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VU 


;Input buffer 
;Echo flag 


7Set stack 


;Read next line 
;Start of buffer 


7Check for non=blank 


7Get value 


U 
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ENDC — Ends Conditional Assembly Code 
Syntax 
ENDC 
Description 


The ENDC directive informs the assembler where the source code, which is subject 
to the conditional assembly statement, ends. In the case of nested IF xx statements, 
an ENDC is paired with the most recent IF xx statement. 


Example 


MOVE #22,D2 
IFEQ SUM-4 


ORI #200,D3 7 assembled if 

ADD DO, VALUE+3 7 SuM-4 is non-zero 
ELSEC 

ORI #51F,D3 ; assembled if 

ROL #1,D0 + SUM-4 is zero 
ENDC 


In the example, if the expression sum-4 is equal to zero, the instructions between 
the IFEQ and ELSEc directives will not be assembled and those between the ELSEC 
and ENpc will be assembled. If sum-4 is non-zero, the opposite occurs. To inhibit 
listing the non-assembled instructions, you can use the OPT -I directive. 
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ENDR — Ends Repeat O 
Syntax 
ENDR 
Description 


The ENDR directive ends a repeat statement as defined in the REPT or IRP or IRPC 
directives. Note that ENDR does not terminate a macro definition. 


Example 


IRP Dl 
ADD DO, VALUE+3 
ENDR 


O 


O 
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EQU — Equates a Symbol to an Expression 


Syntax 


label EQU {expression | keyword} 


Description 
label 


expression 


keyword 


Defines symbol name. 


Sets the symbol to the value of expression for the duration of 
the current assembly, Any attempt to reequate the same label 
will result in an exror. 


Any symbol used in expression must have been previously 
defined or externally defined. If expression uses previously 
defined symbols, the standard expression rules apply (see the 
Expressions section in Chapter 2, Assembly Language). If 
expression uses an externally defined symbol, a constant 
number can be added or subtracted from the symbol. 


Sets the symbol to the value of keyword, which is a keyword 
defined by the assembler or a symbol previously defined by 
the EQU directive as a keyword. 


The EQU directive causes the assembler to assign a particular value to a new label. 
The new label can be an absolute symbol, a relocatable symbol, or even an external 
symbol. If a symbol is equated to an expression containing an external symbol, the 
expression cannot contain any other relocatable terms. 


EQU also defines new keywords instead of the predefined assembler keywords. 
This lets you assign meaningful names to processor registers. 


Examples 
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EQU D7? ¢ data register 

EQU AS * address register 

ErQu 20 + ASCII value for a space 

EQU BUFF + label at beginning of a buffer 
XREF xrefsymbol # externally defined symbol 


EQU) xrefsymbol+7 
EQU xrefsymbol-3 
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FAIL — Generates Programmed Error 
Syntax 
FAIL [expression] 
Description 


expression Defines the number of the FAIL directive. expression is a 
32-bit absolute value and does not contain any forward 
references. The default value is 0. 


The FAIL directive indicates an error or warning in the listing and error summary. 
The typical place for this directive is within convoluted nestings of macros and 
conditional assemblies to mark a path of assembly that would never be taken if the 
code did what you intended. 


When a FAIL directive is assembled, the assembler marks it with a fail 
encountered error message or warning and displays the value of expression in the 
address field of the listing. If the value of expression is 500 or more, a warning is 
generated; otherwise, an error message is generated. 
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Example 


Command line: asm68k -1 fail 


Line Address 
1 oo0000001 true EQU 1 
2 00000000 false EQU 0 
3 
4 00000000 test SET false 
5 IFEQ test 
6 00000000 4E71 NOP 
y ELSEC’ 
8 FAIL 444 
9 ENDC 
10 
1i 00000001 test SET true 
12 IFEQ test 
13 NOP 
14 ELSEC 
15 000001BC FAIL 444 
** ERROR: (591) FAIL directive assembled. 
16 ENDC 
i7 
c 18 00000001 test SET true 
Cs 19 IFEQ test 
; 20 NOP 
aaa 21 ELSEC 
22 00000220 FAIL 544 : 
** WARNING: (591) FAIL directive assembled, 
23 ENDC 
24 END 
Symbol Table 
Label Value 
false 00000000 
test aco00colL 
true 00000001 
Errors: 1, Warnings: 1 


0 
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FAIL 


; this time pass 


; this time fail 


; fail with error 


; this time fail 


fail with warning 
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FEQU — Equates a Symbol to a Floating-Point Expression WY 


Syntax 


label FEQU(.qualifier| floating point_expression 


Description 


label Defines a symbol name. 

qualifier Specifies the symbol type. qualifier can be: 
.S Single precision 
-D Double precision 


-x Extended precision 
-P Packed decimal 


The default is .x. 


floating point_expression 
Sets value of Jabel for the duration of the current assembly. 
An attempt to reequate the same label will result in an error. 
Any symbols used in the expression must have been 


previously defined. a 
The FEQU directive assigns a floating-point expression to a symbol. ASM68K. Y 
supports the TEEE-695 standard floating-point number format with an optional 
exponent. Floating-point numbers can be in either decimal or hexadecimal format. 
A decimal floating-point number must contain either a decimal point or an E 
indicating the beginning of the exponent field. 


Underscores can occur before or after the E to increase readability. Underscores are 
ignored in determining the value of a constant. 


A hexadecimal floating-point number is denoted by a colon (:) followed by a series 
of hexadecimal digits (up to 8 digits for single precision or 16 digits for double 
precision). The digits specified are placed in the field as they stand. You are 
responsible for determining how a given floating-point number is encoded in 
hexadecimal digits. If fewer digits than the maximum permitted are specified, the 
ones that are present will be left-justified within the field. Thus, the first digits 
specified always represent the sign and exponent bits. 


Examples 


COUNT] FEQU 3.14159 

COUNT2 FEQU -22E-100; ; Equivalent to -22 ® 107100 
COUNT3 FEQU 123.45 

COUNT4 FEQU :9AB 


Q 
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ee FOPT — Sets Floating-Point Options 
Syntax 
FOPT ID=n 
Description 
n Specifies the coprocessor ID field. The range of n is 0 


through 7. 


The FOPT directive specifies the coprocessor ID field (0 through 7) used in 
subsequent 68881/82 floating-point instructions. If unspecified, the default 
6888 1/82 coprocessor ID is 1. 


Examples 
FOPT IDe2 } Specifies 68681/82 id # 2 
FMOVE.D #2,0,FPQ ; Move to 68881/82 id # 2 
FOPT ID=1 + Specifies 68881/82 id # 1 
? 


FMOVE.D #2.0,FP0 Move to 68881/82 id # 1 
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FORMAT — Formats Listing 
Syntax 
(NO1FORMAT 
Description 


ASM68K does not require this directive but recognizes it for compatibility with the 
Motorola FORMAT directive. 


Motorola uses the FORMAT directive to format the source listing. NOFORMAT 
prevents the formatting of the source listing. 
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C) IDNT — Specifies Module Name 
Syntax 
name IDNT 
Description 
name | Specifies the module name which is passed to the linker. 


This name must follow all the rules of a symbol, and must 
appear in the label field of the statement. The operand field 
of the statement is ignored. 


The IDNT directive assigns a name to the object module produced by the 
assembler. It is identical in function to the NAME directive. However, IDNT 
allows only legal identifiers for the module name, while NAME allows an arbitrary 
sequence of characters. Only one IDNT directive should appear in a program. 


If you do not use the IDNT directive, the default object moduie name will be the 
Same root name as the assembler input source file name (without path and 
extension). 


x Example 


¢ LAB1 IDNT 
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IFC — Checks if Strings Equal (Conditional Assembly) 


Syntax 


IFC [string] }, (string?) 
IFNC [string!], [string2} 


Description 


string] ’ Represents a string of characters (see rules below). 


string2 Represents a string of characters (see rules below). 


The IFC directive tests whether two strings are equal. Depending on the result of 
the comparison, statements up to the next ELSEC or ENDC will or will not be 
assembled (like the IF statement). This directive takes two string arguments, both 
optional, separated by a required comma, 


The following rules are applied to string/ (note that the term nonblank excludes tab 
characters also): 


If the first nonblank character following the directive is a comma, the 
first string is null. 


If the first nonblank character following the directive is a single quote, 
the first string consists of all characters from this quote to the matching 
closing quote, including the delimiting quotes. Two adjacent quotes 
represent a quote character within the string. In this case, the next 
nonblank ‘after the closing quote must be a comma and blanks between 
the closing quote and the comma are not significant. Commas can be 
used between the quotes as part of the string. 


if the first nonblank character following the directive is neither a comma 
nor a single quote, the first string consists of all characters from this one 
to the last nonblank before the first comma on the line. The comma is 
not part of the string. An unbalanced quote can be part of a string in this 
format. Note that a string in this format cannot contain commas. 


The first string is always terminated by a comma, which is referred to 
below as the delimiting comma. 
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C) The following rules are applied to string2 (note that the term nonblank excludes tab 
characters also): 


¢ If there are no nonblanks after the delimiting comma, the second string 
is null. 


¢ If the first nonblank after the delimiting comma is a semicolon, the 
second string is null. 


+ If the first nonblank after the delimiting comma is a single quote, the 
second string extends from this quote to the terminating quote, as for the 
first string. Any characters after the terminating quote are ignored. 


e = If the first nonblank after the delimiting comma is not a single quote or 
a semicolon, the second string extends from the first nonblank following 
the delimiting comma to the last nonblank before the first semicolon 
following the delimiting comma, or if there is no semicolon following 
the delimiting comma, to the last nonblank on the line. In this format, 
the first semicolon after the delimiting comma is considered a comment 
delimiter, It and all characters after it are ignored. Note that in this 
format, the second string cannot contain semicolons. 


‘ A string delimited by quotes or up arrows is always unequal to a string not delimited 
C by quotes, so it is not advisable to mix these two forms. 


Examples 


IFC ‘STRING’ , ‘STRING’ 
IFC A'\1°,A"\2° 

IFC *\1",°\2° 

IFrc \1,\2 

IFrc string , string 
IFc string , string 


Equal- assembly continues 

Always unequal 

Parameters are expanded 
Parameters are expanded 

Equal (blanks not significant) 
Unequal (no terminating semicolon} 


a Ce 


oS 
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IFDEF — Checks if Symbol Defined (Conditional Assembly) YY 


Syntax 


IFDEF symbol 
Description 
symbol Represents any legal assembler symbol. 


The IFDEF directive determines whether the symbol is defined or has been 
declared external. If the symbol has been defined or declared external, the IFDEF 
directive assembles code up to the next ENDC or ELSEC directive. No forward 
teference is allowed. 


Example 


IFDEF LABEL 


0) 
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IFEQ — Checks if Value Equal to Zero (Conditional Assembly) 
Syntax 
IFEQ expression 
Description 


expression Evaluates to a value that determines whether or not the 
assembly between the IFEQ and the following ELSEC or 
ENDC will take place. Any symbols used in this expression 
must have been previously defined. The expression cannot 
be relocatable. 


The IFEQ directive conditionally assembles source text between the IFEQ 
directive and the ELSEC or ENDC directive. When expression is equal to zero, the 
code will be assembled. For example, IFEQ 5 will not cause the following code to 
be assembled while IFEQ 0 will. 


IFEQ statements can be nested up to 16 levels and appear at any place within the 
source text. 


Note 


The IFEQ directive performs a signed comparison, treating 
expression as a two’s complement 32-bit signed integer ranging 
from -$80000000 to +$7FFFFFFF. In contrast, the logical 
operator = perferms unsigned comparisons, treating operands as 
32-bit unsigned integers ranging from 0 to +$FFFFFFFF. 
Therefore, IFEQ x is not equivalent to IFNE x=0, Logical 
operators return a value of $FFFFFFFF for true and zero for false. 
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Example 
Line Address 
i 1 opt not 
H 2 00000001 ONE EQU 1 
i 3 00000000 ZERO EQU 0 
4 IFEQ ZERO 
; 5 00000000 4E71 NOP + assembled 
6 00000002 4E71 NOP ; assembled 
7 ELSEC 
: 8 NOP 7; unassembled 
9 NOP ; unassembled 
10 ENDC 
11 IFEQ ONE 
12 NOP ; unassembled 
13 NOP ; unassembled 
14 ELSEC 
BR) 00000004 4E71 NOP ; assembled 
16 00000006 4E71 NOP / assembled 
17 ENDC 
18 END 


OC | 
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C) IFGE — Checks if Value Non-Negative (Conditional Assembly) 
Syntax 
IFGE expression 
Description 


expression Evaluates to a value that determines whether or not the 
assembly between the IFGE and the following ELSEC or 
ENDC will take place. Any symbols used in this expression 
must have been previously definéd. The expression cannot 
be relocatable. 


The IFGE directive conditionally assembles source text between the IFGE 
directive and the ELSEC or ENDC directive. When expression is greater than or 
equal to zero, the code will be assembled. For example, IFGE 5 will cause the 
following code to be assembled while IFGE -5 will not. 


IFGE statements can be nested up to 16 levels and appear at any place within the 
source text. 


a | : Note 


The IFGE directive performs a signed comparison, treating 
expression a3 a two’s complement 32-bit signed integer ranging 


from -$80000000 to +$7FFFFFFF. In contrast, the logical 
operator >= performs unsigned comparisons, treating operands as 
32-bit unsigned integers ranging from 0 to +$FFFFFFFF. 
Therefore, IFGE x is not equivalent to IFNE x>=0. Logical 
operators return a value of $FFFFFFFF for true and zero for false. 
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lIFGT — Checks if Value Greater Than Zero (Conditional Assembly) Y 


Syntax 
IFGT expression 
Description 


expression Evaluates to a value that determines whether or not the 
assembly between the IFGT and the following ELSEC or 
ENDC will take place. Any symbols used in this expression 
must have been previously defined. The expression cannot 
be relocatable, 


The IFGT directive conditionally assembles source text between the IFGT 
directive and the ELSEC or ENDC directive. When expression is greater than zero, 
the code will be assembled. For example, IFGT 5 will cause the following code to 
be assembled while IFGT -5 will not. 


IFGT statements can be nested up to 16 levels and appear at any place within the 
source text. 


Note wo) 


The IFGT directive performs a signed comparison, treating 
expression as a two’s complement 32-bit signed integer ranging 


from -$80000000 to +$7FFFFFFF. In contrast, the logical 
operator > performs unsigned comparisons, treating operands as 
32-bit unsigned integers ranging from 0 to +$FFFFFFFF. 
Therefore, IFGT x is not equivalent to IFNE x>0. Logical 
operators return a value of $FFFFFFFF for true and zero for false. 


U 
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C IFLE — Checks if Value Non-Positive (Conditional Assembly) 


Syntax 
IFLE expression 
Description 


expression Evaluates to a value that determines whether or not the 
assembly between the IFLE and the following ELSEC or 
ENDC will take place. Any symbols used in this expression 
must have been previously defined. The expression cannot 
be relocatable. 


The IFLE directive conditionally assembles source text between the IFLE 
directive and the ELSEC or ENDC directive. When expression is greater than or 
equal to zero, the code will be assembled. For example, IFLE -5 will cause the 
following code to be assembled while IFLE 5 will not. 


IFLE statements can be nested up to 16 levels and appear at any place within the 
source text. 


i. Note 


The IFLE directive performs a signed comparison, treating 
expression as a two's complement 32-bit signed integer ranging 


from -$80000000 to +$7FFFFFFF. In contrast, the logical 
operator <= performs unsigned comparisons, treating operands as 
32-bit unsigned integers ranging from 0 to +$FFFFFFFF. 
Therefore, IFLE x is not equivalent to IFNE x<=0. Logical 
operators return a value of $FFFFFFFF for true and zero for false. 


CO 
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IFLT — Checks if Value Less Than Zero (Conditional Assembly) 
Syntax 
IFLT expression 
Description 


expression Evaluates to a value that determines whether or not the 
assembly between the IFLT and the following ELSEC or 
ENDC will take place. Any symbols used in this expression 
must have been previously defined. The expression cannot 
be relocatable. 


The IFLT directive conditionally assembles source text between the IFLT 
directive and the ELSEC or ENDC directive. When expression is greater than or 
equal to zero, the code will be assembled. For example, IFLT -5 will cause the 
following code to be assembled while IFLT § will not. 


IFLT statements can be nested up to 16 levels and appear at any place within the 
source text. 


Note 


The {FLT directive performs a signed comparison, treating 
expression as a two’s complement 32-bit signed integer ranging 
from -$80000000 to +$7FFFFFFF. In contrast, the logical 
operator <= performs unsigned comparisons, treating operands as 
32-bit unsigned integers ranging from 0 to +$FFFFFFFF. 
Therefore, IFLT x is not equivalent to IFNE x<=0. Logical 
operators return a value of $FFFFFFFF for true and zero for false. 


6-34 Microtec Research, Inc. 


U 


©) 


e 


Assembler Directives 


IFNC — Checks if Strings Not Equal (Conditional Assembly) 


Syntax 


IFNC [String]], (string2} 


Description 
string] 
Sstring2 


Represents a string of characters (see mules below). 
Represents a string of characters (see rules below), 


The IFNC directive tests whether two strings are unequal. Depending on the result 
of the comparison, statements up to the next ELSEC or ENDC will or will not be 
assembled (like the IF statement). This directive takes two string arguments, both 
optional, separated by a required comma. 


The following rules are applied to string] (note that the term nonblank excludes tab 
characters also): 


Microtec Research, Inc. 


If the first nonblank character following the directive is a comma, the 
first string is null. 


If the first nonblank character following the directive is a single quote, 
the first string consists of all characters from this quote to the matching 
closing quote, including the delimiting quotes. Two adjacent quotes 
represent a quote character within the string. In this case, the next 
nonblank after the closing quote must be a comma and blanks between 
the closing quote and the comma are not significant. Commas can be 
used between the quotes as part of the string. 


If the first nonblank character following the directive is neither a comma 
nor a single quote, the first string consists of all characters from this one 
to the last nonblank before the first comma on the line. The comma is 
not part of the string. An unbalanced quote can be part of a string in this 
format. Note that a string in this format cannot contain commas. 


The first string is always terminated by a comma, which is referred to 
below as the delimiting comma. 
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The following rules are applied to string2 (note that the term nonbiank excludes tab 
characters also): 


If there are no nonblanks after the delimiting comma, the second string is null. 


If the first nonblank after the delimiting comma is a semicolon, the second 
string is null. 


If the first nonblank after the delimiting comma is a single quote, the second 
string extends from this quote to the terminating quote, as for the first string. 
Any characters after the terminating quote are ignored. 


If the first nonblank after the delimiting comma is not a single quote or a 
semicolon, the second string extends from the first nonbiank following the 
delimiting comma to the last nonblank before the first semicolon following the 
delimiting comma, or if there is no semicolon following the delimiting comma, 
to the last nonblank on the line. In this format, the first semicolon after the 
delimiting comma is considered a comment delimiter. It and all characters after 
it are ignored. Note that in this format, the second string cannot contain 
semicolons. 


A string delimited by quotes or up arrows is always unequal to a string not delimited by 
quotes, so it is not advisable to mix these two forms. 


Exampies 
IFNC ‘string’,’ string’ 7 Umequal (blank in 2nd 
os ; string) assembly continues 
IFNC ‘abc’,’ abe!’ . : Equal-assenmbly does not continue 


Microtec Research, Inc. 


9 


GQ 


UO 


Assembler Directives IFNDEF 


&. IFNDEF — Checks if Symbol Not Defined (Conditional Assembly) 
Syntax 
IFNDEF symbol 
Description 
symbol Represents any legal assembler symbol. 


The IFNDEF directive determines whether the symbol is defined or has been 
declared external. If the symbol has not been defined or declared external, the 
IFNDEF directive assembles code up to the next ENDC or ELSEC directive. No 
forward reference is allowed. 


Examples 


IFNDEF LABEL 


a 
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IFNE — Checks if Value Unequal to Zero (Conditional Assembly) 
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Syntax 
IFNE expression 
Description 


expression Evaluates to a value that determines whether or not the 
assembly between the IFNE and the following ELSEC or 
ENDC will take place. Any symbols used in this expression 
must have been previously defined. The expression cannot 
be relocatable. 


The IFNE directive conditionally assembles source text between the IFNE 
directive and the ELSEC or ENDC directive. When expression is greater than or 
equal to zero, the code will be assembled, For example, IFNE 5 will cause the 
following code to be assembled while IFNE 0 will not. 


IFNE statements can be nested up to 16 levels and appear at any place within the 
source text. 


Note 


The IFNE directive performs a signed comparison, treating 
expression as a two’s complement 32-bit signed integer ranging 


from -$80000000 to +$7FFFFFFF. In contrast, the logical 
operator <> performs unsigned comparisons, treating operands as 
32-bit unsigned integers ranging from 0 to +$FFFFFFFF. 
Therefore, IFNE x is not equivalent to IFNE x<>0. Logical 
operators return a value of $FFFFFFFF for true and zero for false. 


Microtec Research, inc. 


rm 


‘a 


*. 


oO 


O 


Assembier Directives INCLUDE 


INCLUDE — Includes Source File 


Syntax 


INCLUDE filename 


Description 


filename Names the assembler source file to be inserted. 


The INCLUDE directive inserts an external source file into the input source code 
stream at assembly-time. INCLUDE statements can be nested, and they can include 
macro calls, A macro call can also contain an INCLUDE directive. 


The INCLUDE file name is passed to the host operating system as specified 
without any lower- to upper-case conversion. 


Default search paths can be set from the command line. The assembler will first 
search in the current directory for the named INCLUDE file and then in the 
specified directories. For information on the correct syntax, see the Microtec 
Research ASMO8K User's Guide. 


Example 


INCLUDE EXTERNAL .SRC 
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UO 
IRP — Specifies Indefinite Repeat 
Syntax 
(label] IRP model_parameter(,actual_parameter|... 
Description 


label Assigns the address of the current program counter to label. 


model parameter _ Specifies a parameter name. 


actual parameter _ Specifies parameters that are to be substituted into the 
model_parameter. 


The IRP directive repeats a sequence of statements enclosed by the IRP and ENDR 
directives once for each actual_parameter. Each actual_parameter is substituted in 
place of model_parameter. Parameter substitution is identical to that which is 
performed in a macro. If no actual_parameter is specified, the macro is expanded 
once with a null replacing the model_parameter. 


Like macro definitions, repeat directives cannot be nested. Only one macro 
definition can be used inside a repeat directive. a 
Example Y 


The following example shows an inp directive, a model parameter, and actual 
parameters. 


OrT M 
XREF SUB1, SUB2,SUB3 


+ Three JSR instructions 
7 are generated 
IRP DUMMY, SUB1,SUB2,SUB3 
JSR DUMMY 


ENDR 
END 


6-40 Microtec Research, inc. 


Assembler Directives IRP 


7 The resulting expansion is shown below: 


Line Address 
OPT M 
XREF SUB1, SUB2, SUB3 


; Three JSR instructions 

; are generated. 
IRP DUMMY, SUB1,SUB2,SUB3 
JSR DUMMY 


ENDR 
00000000 4EB9 0000 0000 E JSR SUBIL 


00000006 4EBS 0000 0000 E JSR SUB2 


OQcoo000c 4EB9 0000 0000 £ JSR SUB3 


rPwYNYHwuUvVvUW WY CAKHYU &SWNE 
Ao wn te 


0 END 


‘a 
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IRPC — Specifies Indefinite Repeat Character 
Syntax 
tlabel] xirPC model_parameter{,actual_parameter] 


Description 


label Assigns the address of the current program counter to label. 
model parameter _—_ Specifies a parameter name. 


actual parameter Specifies parameters that are to be substituted into the 
model_parameter. 


The IRPC directive repeats a sequence of statements once for each character of 
actual_parameter. The IRPC directive can be terminated with the ENDR directive. 
If no actual_parameter is specified, the macro is expanded once with a null 
replacing the model_parameter. 


Like macro definitions, repeat directives cannot be nested. Only one macro 
definition can be used inside a repeat directive. 


Example 
Command line: asm68k ~l irpcout C) 
Line Address 
2 XREF SUB 
2 
3 IRPC DUMMY, 1234 
4 MOVE #DUMMY, DO 
-] sFour MOVE and JSR instructions generated 
6 JSR SUB 
7 ; ENDR 
Tal 00000000 303c 0001 . MOVE #1,D0 
TZ }Four MOVE and JSR instructions generated 
7.3 00000004 4EB9 0000 0000 E JSR SUB 
7.4 OOOD000A 303¢ 0002 MOVE #2,D0 
7.5 ;Four MOVE and JSR instructions generated 
7.6 QOOOQ00E 4EB9 0000 0000 FE JSR SUB 
7.7 00000014 303c 0003 MOVE #3,D0 
7.8 ;Four MOVE and JSR instructions generated 
7.9 c0000018 4E89 0000 0000 E JSR SUB 
7.10 OOOOD01E 303¢ 0004 MOVE #4,D0 
7.11 :Four MOVE and JSR instructions generated 
7.12 00000022 4EB9 0000 0000 E JSR SUB 
8 END 
Symbol Table 
Label Value 
SUB External 
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C) LIST — Generates Assembly Listing 
Syntax — 
[NO] LIST 
Description 


The LIST directive prints an assembly listing. The assembly listing is printed by 
default (LIST). When NOLIST is used, an assembly listing is not printed. 


The OPT S directive is synonymous with the LIST directive. 


a 
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LLEN — Sets Length of Line in Assembler Listing 


Syntax 
LLEN 7 
Description 
n Specifies the number of characters in a line for the assembler 
listing. » must be between 37 and 1120 inclusive. The default 
line length is 132. 


The LLEN directive changes the length of the line on the source listing. The value 
of 113 allows printing of the full 80 columns of the input source. 


This directive does not affect the header lines at the top of each page, which are 
printed in a fixed-length format. 


Example 


LLEN 128 
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@ MASK2 —- Generates Code to Run on MASK2 (R9M) Chip 
Syntax . 
MASK2 
Description 


The MASK2 directive is recognized for Motorola compatibility, Its use will not 
generate an error, but the instruction is ignored. 


O 
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a NT el 


NAME — Specifies Module Name 
Syntax 
NAME icdlienan 
Description 
modulename Specifies the module name within the object file. 


The NAME directive assigns an internal module name to the object module 
produced by the assembler; the object file name is unchanged. It is identical in 
function to the IDNT directive. However, the syntax of NAME allows the module 
name to be an arbitrary sequence of characters, while IDNT allows only legal 
identifiers. Only one NAME or IDNT directive should appear in a program. 


If you do not specify a NAME or IDNT directive, the default module name is the 
input file name without path and extension. 


Note 


The module name will consist of every character up to the end 
of the line including white space and comments. 
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NOOBJ — Does Not Create an Output Object Module 
Syntax 
NOOBT 
Description 
The NOOB] directive suppresses creation of the output object module. 
The OPT -O directive is synonymous with NOOB]. 
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OFFSET — Defines Table of Offsets 


Syntax 


OFFSET expression 


Description 


expression Specifies new value for the location counter. This absolute 
expression cannot contain any references that make the 
expression relocatable. 


The OFFSET directive defines a table of absolute offsets. It is present for 
convenience and Motorola compatibility but performs no function that cannot be 
handled with EQUs. 


The OFFSET directive is much like ORG in that it terminates the previous section 
and alters the location counter to an absolute value. However, an OFFSET section 
cannot contain instructions or any code-producing directives. SET, EQU, REG, 
XDEF, and XREF directives are allowed. DC and DCB directives are illegal 
within an OFFSET section. The OFFSET section must be terminated by an ORG, 
OFFSET, SECT, SECTION, COMMON, or END directive. 


The typical use for OFFSET is to define a storage template in mnemonic terms. For 
example, suppose you want to define an array of 80 by 24 bytes representing a 
terminal screen. Since two dimensional arrays are not available in assembly 
language, the array must be defined as one dimensional: SCREEN DS.B 80*24. 
You could set up the offsets ROW1, ROW2, etc., so that line I of the screen can be 
accessed as ROWI, as shown in the following example. 


Example 


An example of template definition through the use of EQu: 
SCREEN DS.B 80*24 


ROW1 EQU SCREEN 
ROW2 EQU SCREEN+80 
ROW3 EQU SCREEN+160 
END 
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OFFSET 


The use of of FsET for template definition provides a clearer alternative for complex 
structures: 
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ROWL: 
ROW2: 
ROW3: 


OFFSET 0 

OFFSET 80 
OFFSET 160 
OFFSET 240 


END 
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Syntax 


Description 


ABSPCADD 


BRS 


BRB 
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OPT — Sets Options for Assembly 


OPT [- | NO] IBICIDIEIF])GIIIMIOIPITRIS|I|TIX 
{|W | ABSPCADD | BRL | BRS | BRW | BRB | CASE | CEX |] CL | CRE 
| FRL | FRS { MC { MD | MEX [ NEST=n | OLD [| OP#@n | P=chip(/cotypel 
| PCO | PCR | PCS } QUICK | REL32] 


An absolute expression appearing in conjunction with the 
mnemonic PC refers to an address rather than an absolute 
displacement. 5(PC) would refer to absolute address 5, using 
with PC-relative mode, rather than S+current_PC. This 
option applies to the base displacement, not the outer 
displacement, in the 68020 expressions containing square 
brackets. This option can be tumed on and off at your 
discretion. The last ABSPcapD setting applies. For more 
information on this option, see Addressing Mode Syntax in 
Chapter 4, Addressing Modes. 

(default: ABSPCADD) 


Forces forward references in relative branch instructions 
(Bcc, BRA, BSR) to use the short form of the instruction (8- 
bit displacement). 


In 68020 mode when OPT OLD has not been set, BRW and 
-B are synonymous.In 68020 mode, when opt OLD has 
been set, BRL and BRW are both synonyms for -B, and 
there is no way to specify that forward references will use 
32-bit displacements. 

In processor modes other than 68020, BRL is a synonym for 
-B and BRW is illegal. 

(default: NosRs) 


Forces forward references in rfelative branch instructions 
(Bcc, BRA, BSR) to use the short form of the instruction (8- 
bit displacement). BRB is legal only in 68020 mode. 
(default: NopRB) 
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BRL 


BRW 


CASE 


cL 


CRE 
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Forces the long addressing mode to be used in relative 
branch instructions (Bcc, BRA, BSR) that have forward 
references. 


In 68020 mode, when OPT OLD has not been specified, 
32-bit displacements are used. In 68020 mode, when OPT 
OLD has been specified, 16-bit displacements are used. In 
all other processor modes, 16-bit displacements are used. 
(default: NOBRL)} 


Forces 16-bit displacements to always be used in relative 
branch instructions (Bcc, BRA, BSR) that have forward 
references. 

(default: BRW) 


Lists all lines of object code that are generated by the DC 
directive. This option does not affect the DCB directive. cEx 
and c are synonymous. 

(default: cEx) 


Retains case-sensitivity of symbols. For example, LOOPS is 
different from loopS. If Nocasez is used, all symbols will be 
converted to uppercase. 

(default: casE) 


Lists instructions that are not assembled due to conditional 
assembly statements. cL and I are synonymous. 
(default: cx) 


Lists the cross-reference table on the output listing. The crE 
option overrides the symbol table output option, r. If both T 
and CRE afe specified, a cross-reference table will be 
generated. CRE is a synonym for x. 

(default = wocrE) 


Places local symbols in the absolute or relocatable output 
object module, which is useful for debugging. This option 
must also be specified before any instruction that generates 
object code. If opt CASE is used, symbols will be placed in 
the object module as defined. 

(default: Nop) 
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E 


Lists lines with errors on your terminal as well as on the 
output listing. For a listing of just errors, you can turn off the 
source listing and only the errors will appear on the normal 
output device. 

(default = £) 


Forces instructions containing forward references to an 
absolute (non-relocatable) address to use a 16-bit address 
(short form) instead of a 32-bit address. This option does not 
cause instructions to use an absolute addressing mode but 
applies to all instructions that can use absolute addressing 
modes, specifically excluding the Bxx instructions. rrs is a 
synonym for Fr, and FRL is a synonym for -F. 

(default: Norrs) 


Forces instructions containing forward references to an 
absolute (non-relocatable) address to use a 32-bit address 
instead of a 16-bit address. FRL is a synonym for -F. 
(default: 32-bit address or FRL) 


Lists assembler-generated symbols in the symbol or cross- 
reference table. If p is also set, these symbols are placed in 
the object module as well. 

(default: noc) 


Lists instructions that are not assembled due to conditional 
assembly statements. cu and 1 are synonymous. 
(default: cx) 


Lists macro and structured conitrol directive expansions on 
the program listing. 
(default: mex) 


Lists macro calls on the program listing. When the expansion 
of one macro contains a call to another macro, either nom or 
nomc will suppress listing the nested call. 

(default: uc) 


Lists macro definitions on the program listing. 
(default: mp) 
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OP=n 


P=chip [ /cotype) 
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Sets the nesting levels for macros. The default is set to the 
maximum number of nesting levels. 


(default: NEst=100 (UNIX/VMS) or nest=8 (DOS)) 


Produces the output object module. 
(default: 0) 


Forces the assembler to generate 16-bit displacements for 
Bcc instructions when opT BRL or OPT -B are specified, or 
when explicit .L qualifiers are used (as appropriate for the 
68010 and earlier processors) even though the processor 
mode has been set to 68020. This is convenient for migrating 
68000 programs onto the 68020 microprocessor. 

(default: op) 


Resets the maximum number of optimization loops that the 
assembler will do if opr opnop is set. The assembler will 
discontinue looping if there is a pass in which no 
optimization occurs. 

(default: op=3) 


Uses the program counter with displacement addressing 
mode on backward references within the absolute (ORG) 
section, provided that this addressing mode is legal for the 
instruction and that the displacement from the program 
counter fits within the 16-bit field provided. This option does 
not affect references either from or to a relocatable section. 
(default: norco) 


Identifies the target processor and coprocessor. Valid type 
values include:68000, 68008, 68010, CPU32, 68020, 68030, 


or 68040. Valid coprocessors (cotype) include: 68851 or 
68881. 


The 68851 coprocessor is compatible with all of the other 
processors with the exception of the CPU32, 68030, and 
68040. Similarly, the 68881 coprocessor is compatible with 
all of the processors with the exception of the CPU32. 
Example 

P=68020 


The p-chip option is distinguished from ort P by the equal 
sign which must immediately follow the Pp. See the CHIP 
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PCR 


PCS 


QUICK 
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directive (which is equivalent to opt P=) for a discussion of 
the differences between the various target processors. 


The preceding No or minus sign is not permitted with this 


' pechip option. 


(default: 68000/68881) 


Uses the program counter relative addressing mode on 
references from a relocatable section to the same section 
within the current module for all instructions for which this 
is a legal addressing mode. Pcr differs from Pcs in that Pcs 
applies to all relocatable sections within this module and 
assumes you know the boundaries. pcr will affect only 
intrasection expressions within the current module 
(expressions for which the assembler has enough 
information to generate the correct relative offset). 

(default: NopcR) 


Uses the program counter relative addressing mode on 
backward references from a relocatable section to the same 
section or to a different relocatable section for all 
instructions for which this is a legal addressing mode. This 
does not affect forward references. If R is on and a backward 
reference within a relocatable section results in a 
displacement larger than 16 bits, it is considered an error. 


. (default: wopcs) 


Changes the MOVE, ADD, and SUB instructions to the 
more efficient MOVEQ, ADDQ, and SUBQ instructions. 


Before the Change After the Change 


MOVE.L #data, Dn MOVEQ #data, Dn 
ADD #data, ea ADDQ_ #data, ea 
SUB #data, ea SUBQ  #data, ea 


where: 


data Legal values are -128 to 127 for MOVE and 
MOVEQ instructions. 


Legal values are 1 to 8 for ADD, ADDQ, 
SUB, and SUBQ instructions. 


ea Effective address. 
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REL32 


OPT 


For more information on these instructions, see a Motorola 
Microprocessor User’ s Manual. 
(default: quick) 


Forces the assembler to default to 32-bit base and outer 
displacements when the address range is 32 bits long. 
~ 


Addressing modes which first appeared with the 68020: 


((bd,An,Xn) ([bd,An,Xn],0d) ([bd,An],Xn,od) 
(bd,PC,Xn) ([bd,PC,Xn],od) ([bd,PC],Xn,od)) 


defaulted the size of the outer and base displacements to 
word for forward references, external references, complex 
expressions, and relocatable expressions. While the code 
produced was smaller, you had to always size cast dis- 
placement expressions if you had a processor that accessed 
a full 32-bit address range (68020/30). The REL32 flag lets 
you change the default to 32 bits without size casting dis- 
placement expressions. This flag can be tumed on and off 
at any time in the program. It will only be effective if the 
processor type is set to 68020, 68030, or 68040. 

(default: norz1L32) 


Lists the source text on the output listing. The directives 
LIST and NOLIST are other ways to specify opt s and opt 
-S respectively. 

(default: s) 


Lists the symbol table on the output listing. 
(default: T) 


Prints wamings during the assembly. 
(default: 4) 


Lists the cross-reference table on the output listing. The x 
option overrides the symbol table output option, 1. If both tT 
and x are specified, a cross-reference table will be generated. 
CRE is a synonym for x. 

(default: NocrE) 


The OPT directive generates listings of the elements specified. It influences the 
_assembler’s choice of addressing modes in ambiguous situations and controls the 
form of the object output. 
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The defaults in the assembler are: 


# The source text, symbol table, macro definitions, macro calls, macro 
expansions, and conditional assembly statements not assembled are all 
listed. 


¢ An object module in relocatable format is produced. 
¢ The symbol table is not placed into the object module. 


* References to unknown locations will use an absolute addressing mode 
unless you specifically request otherwise. 


¢ Forward references and external references not associated with a section 
name will leave room for an absolute long address. 


¢ A relative branch to a forward reference will use the long (32-bit 
displacement) form of the instruction. 


e The target chip is the 68000, 
¢ ©The 68881/82 instructions are legal. 


To turn off an option, precede it by a minus sign (-) or the word No. 


Error messages are always listed, regardless of the elements specified. In particular, 
the & option can be used to list error messages on the standard output device. 


; Example 


OPT -CRE,D ; Does not list the cross reference table, 
* Puts the symbol table in the object module. 
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ORG — Begins Absolute Section 
Syntax 
ORG[.qualifier] [expression] {,name] 
Description 


qualifier Specifies the address form for instructions containing for- 
ward references to an absolute (non-relocatable) address. 
The following values are legal: 


s ORGS is interpreted as both ORG and OPT F. 
L ORG.L is interpreted as both ORG and OPT -F. 


expression Replaces the contents of the assembly program counter. 
Bytes subsequently assembled will be assigned memory 
addresses beginning with this value. This expression can 
contain no forward, undefined, or relocatable symbols 
(including external references). 
The form * {+ | -} displacement indicates an absolute 
value, where displacement is a constant number and * 


indicates the ending value of the previous absolute section or 
0 for the first absolute section. 


name Specifies the name of the section. 


The ORG directive begins an absolute section. If the program does not have an 
ORG, SECT, SECTION, or COMMON statement before the first code- 
generating statement, a SECTION 0 is assumed and assembly begins at location 
zero in the relocatable noncommon long section named 0. 


If the ORG directive is used and expression is not specified: 
¢ The F option is unchanged (see the OPT directive in this chapter). 
¢ The location counter is set to the address immediately following the last 


preceding absolute section if there was one; otherwise, the location 
counter is set to 0. 


_* Ifa comment field is present, it must be preceded by semicolon (;) or 
exclamation mark (!). 


All subsequent bytes of code will be assigned sequential addresses beginning with 
the address in the location counter. 


Example 


ORG $100 
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PAGE — Advances Listing Form to Next Page OY 


Syntax 
[NO] PAGE 
Description 


The PAGE directive instructs the assembler to skip to the top of the next page on 
the listing form. You may want to start each subroutine on a new page for 
readability. If the NOPAGE directive was previously specified, this directive is 
ignored. 

The NOPAGE directive suppresses all page ejects and page headers on the output 
listing including those explicitly specified by the PAGE directive. NOPAGE 
affects the entire listing no matter where the directive appears in the program. Once 
paging has been disabled it cannot be re-enabled. 
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PLEN — Sets Length of Listing Page 
Syntax 
PLEN 7” 
Description 


n Specifies the number of lines on an assembly listing page. 
This absolute expression must have a value greater than 12. 


PLEN specifies the number of lines on an assembly listing page. The default value 
is 60. 


Example 


PLEN 58 
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_REG — Defines Register List O 
Syntax 


label RxG register list - 


Description 
label Defines a symbol name. 
register list Specifies a list of registers in the format recognized by the 


MOVEM instruction. It can be any of the following: 


¢ Asingle register. 


e Arrange of consecutive registers of the same type (A 
or D), denoted by the lowest and highest registers to 
be transferred separated by a hyphen (lower one must 
occar first). 


¢ Any combination of the above separated by a slash. 


The REG directive assigns a symbolic name to a register list for future use by the 
MOVEM instruction. The name can be redefined during the assembly as a different 
register list. { ) 


Example 


SAVE REG A1-A5/D0/D2-D4/D7 
MOVEM (A6),SAVE 


és O 


Microtec Research, Inc. 


* 


a 


Assembier Directives : REPT 


REPT — Specifies Repeat 
Syntax 


(label) REPT count 


Description 
label Assigns the address of the current program counter to label. 
count Specifies the number of times to repeat the code. This 
expression cannot be relocatable or contain symbols not 
previously defined. 


The REPT directive repeats a sequence of directives a specified number of times. 
The statements to be repeated are those between the REPT and the following 
ENDR directive. The statements are expanded from the point at which the 
assembler encounters the REPT directive. 


Example 
REPT 3 ; Repeat following lines (until ENDR encountered) 
; 3 times 
DeC.B 'At 
Dc.B 'B! 
ENDR 
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RESTORE — Restores Options 


Syntax 


RESTORE 


Description 


The RESTORE directive restores those options that were previously saved by the 
j SAVE command. Once RESTORE is specified, all options specified after the last 
SAVE will no longer have any effect. 


Example 
OPT P=68010 


SAVE 
OPT P=68020/68881 ; 68020 instructions are now legal 


: CAS DO,D1, {A3) 7 68020 instruction 
% rye ae 
RESTORE 
se + 68020 instructions are no longer legal 
END 
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ies SAVE — Saves Options 


Syntax 
SAVE 
Description 


The SAVE directive saves the current set of OPT options (see the OPT command 
for a list of these options). 


The options can be restored at a later time with the RESTORE command. Once 
RESTORE is specified, all options specified after the last SAVE will no longer 
have any effect. 


Example 
OPT P=68010 


SAVE 
OPT P=68020/68881 ; 68020 instructions are now legal 


CAS DO,D1, (A3} ; 68020 instruction 


RESTORE 
. 7 68020 instructions are no longer legal 


END 
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SECT / SECTION — Specifies Section 
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Syntax 


(label} SECT[.S}] {sname | snumber) [, (align) [, type), Aptype?] 


Description 


label 


sname 


snumber 


align 


type . 


hptype 


Specifies the section name. If snumber is specified, label 
cannot be used. 


Assigns short attribute to the section. All symbols specified 
will be found in an area of memory accessible by 16-bit 
addresses, or they will be constants with 16-bit or smaller 
values. 


? 


Specifies the noncommon section name. Any valid section 
can be used. 


Specifies the section number. Up to two decimal digits can 
be used. 


Specifies the bytes of alignment, either 2 or 4. The section 
alignment attribute lets you specify that a section be located 
on a modulo 2 or modulo 4 boundary. For more information, 
see Chapter 5, Relocation. 


_ Specifies the type of section. It can be: 


c Code 
D Data 

.M Mixed code, data, etc. 
R ROMable Data 


Specifies the HP 64000 section type. It can be: 


A ABS 

P PROG 

D DATA 

c COMN 


SECT and SECTION are equivalent. The statements following the SECT 


directive will be assembled in the specified relocatable section. This remains in _ 


effect until an ORG, OFFSET, COMMON, or another SECT or SECTION 
directive is assembled that specifies a different section. Initially, all section location 
counters ate set to zero. 
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Assembler Directives SECT / SECTION 


You can alternate among the various sections with multiple section directives 
within one program. The assembler will maintain the current value of the location 
counter for each section. 


Each section has a type, which does not affect its placement in memory. Possible 
types are m (mixed code, data, etc.), c (code), p (data), and R (ROMabie data, 
constants). For more information, see Section Type Attributes in Chapter 5, 
Relocation. 


The Aptype refers to the HP 64000 section type. If it is not specified, ASM68K. 
assigns a hptype field according to the following rule: code sections map to PROG, 
data sections map to DATA, and ROMable sections map to COMN subject to the 
following restrictions: 


1. There can be at most one PROG, one DATA, and one COMN section for 
each module. 

2. The second and subsequent sections assigned to PROG, DATA, or 
COMN are called extra sections. Extra sections have ABS in their hptype 
field, and their local symbols cannot be written to the HP asmb_sym file. 


You cannot override the first restriction by explicitly assigning more than one 
section to PROG, DATA, or COMN. If you do so, ASM68K will issue the 
following warning: 


Maximum number of typed sections exceeded in HP mode 


This warning is issued whenever an extra section is created regardless of whether 
the hptype was set explicitly or implicitly. 


If hptype is ABS, the section must be treated as an extra section; that is, the section 
will have no symbols in the asmb_sym file because it is impossible to relocate 
them. For more information on HP 64000 issues, refer to Appendix A, HP 64000 
Development System Support, in your ASM68K User’ s Guide. 


Example 


LABEL1 SECT SECT1 7 Name is SECT1, LABEL1 is 
7 noxmal symbol 
SECT.S CODE,,P ; Name is CODE, noncommon 
+ section, HP type is PROG 
LABEL1 SECTION 0 ; Name is 0, noncommon section 
SECT A,4 7 First byte of section A is 
7 quad-aligned 
+ quad-aligned, section type = 
? program code 
; C section type = data 


SECT B,4,C 


SECT . C,,D 
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SET — Equates a Symbol to an Expression ‘oe 
Syntax 


label SET expression 


Description 
label Specifies symbol name. 
expression Assigns value to label until changed by another set 
directive. Any symbols used in the expression must have 
been previously defined. 


The SET directive sets a symbol equal to a particular value. Unlike the EQU 
directive, multiple SET directives for the same symbol can be placed in a source 
pro . The most recent SET directive determines the value of the symbol! until 
another SET directive is processed. 


Like EQU, this directive can also be used to define new keywords. 


Example 


GO SET 5 
GO SET GO+10 _ 
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er SG I A A ET IS SS TE WEY SE 
SPC — Spaces Lines On Listing 
Syntax 
SPC expression 


Description 


expression Specifies number of lines to skip on the output listing. The 
expression must evaluate to an absolute value. expression 
cannot be relocatable but it can contain forward references. 


The SPC directive causes one or more blank lines to appear on the output listing. It 

lets you format the listing for readability. The directive itself does not appear in the 

listing. 

You can also use a blank source statement to insert blank lines on the listing. 
Example 


SPc 7 
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TTL — Sets Program Heading 


Syntax 
TIL heading 
Description 
heading The title to be placed at the beginning of each page. The 
heading can be up to 60 characters. Additional characters are 
ignored. 


You can optionally delimit the heading with single quotes as 
shown in the example. The quotes are not considered part of 
the title. If the terminating quote is omitted, only the first 60 
characters will be used. 


The TTL directive prints a heading at the beginning of each page of the listing in 


addition to the standard header. The default heading defined by the assembler is — 


blank. This directive must be the first statement in the program if you want a 
specified title to appear on the first page of the output listing. 


‘Example 


{TTL ‘TEST PROGRAM' 
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XCOM — Specifies Weak External Reference 


Syntax 


xcom symbol, size 


Description 


symbol Names a symbol referenced in this module but defined in a 
different module or by the linker. 
size Specifies the size in bytes that the linker will reserve if there 


is no specific public definition for this symbol. 


The XCOM directive specifies a symbol that is referenced in this module but is 
assumed to be defined in a separate module and the symbol remains undefined at 
link time. 


XCOM is a Microtec Research extension to the Motorola assembly language and 
is of limited use to the assembly language programmer. This directive was created 
to support the assembly of compiler-generated assembly code. Some languages, 
like C, permit the referencing of global data items declared cutside the current 
module. In the case where all modules reference the item but none allocate pate 
for it, the size qualifier lets the linker properly account for it. 


XCOM is identical to XREF with the exception that only one symbol per line is 
allowed and a required size qualifier is added. Currently, section and short/long 
specification are not supported. 


XCOM directives can appear anywhere within the program. You can declare 
common symbols to be externally defined multiple times. Common symbol 
references can appear in any section including absolute sections. A common 
reference is presumed to be absolute by default and is valid in certain constructs 
where only absolute values are permitted (e.g., symbol(An)). 


Example 


XCOM PROC1,1 


In this example, the weak external reference for the symbol proc1 assumes that the 
final value is long, If the linker must define its value, one byte of space will be 
reserved for it. 
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XDEF — Specifies External Definition 


Syntax 
XDEF symbol(,symbol)... 
Description 
symbol Specifies an external symbol that can be referenced by other 


modules. 


The XDEF directive specifies a list of symbols that.will be given the external 
definition attribute. These symbols will then be made available to other modules by 
the linker. Symbols appearing in this directive are always placed in the relocatable 
object module. 


XDEF directives can appear anywhere within the program. Symbols that are 

declared with this directive, but not defined in the program, will be flagged as 

undefined in the output listing. Symbols can be declared external multiple times. 
Example 


XDEF SCAN, LABEL, COSINE 
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XREF — Specifies External Reference 


Syntax 


XREF[.S] [sectname:] symbol [, [sectname:} symbol]... 


Description 


8 Assigns short attribute to the section. All symbols specified 
will be found in an area of memory accessible by 16-bit 
addresses, or they will be constants with 16-bit or smaller 
values. 


sectname Specifies section name or number in which the symbol is 
expected to be defined. The linker gives a warning if the 
symbol is defined in a section with a different name. 


symbol Names a symbol referenced in this module but defined in a 
different module. ; 


The XREF directive specifies a list of symbols that are referenced in this module 
but defined in a separate module. External symbol references can appear in any 
section including absolute sections. XREF directives can appear anywhere within 
the program. You can declare symbols to be externally defined multiple times. 


Specifying the section name (or number) of an external reference sometimes affects 
the assembler’s choice of addressing mode (refer to Chapter 4, Addressing Modes, 


-for more information). Also, during the linking process, the linker will verify that 


the externally referenced symbol is indeed in the specified section. 


An extemal reference with no section name or number specified is presumed to be 
absolute by default and is valid in certain constructs where only absolute values are 
permitted (e.g., symbol(An)). 


A section name (or number) applies to all symbols following it until the appearance 
of another section name (or number) or the end of the XREF statement. It is legal 
for a section name that has not been defined to appear in XREF statements. In this 
case, however, the section name counts toward the maximum allowable total 
sections. 


For more information on program sections, refer to Program Sections in Chapter 5, 
Relocation, in this manual. 


Example 


XREF syml, sym2, sect1:sym3,2:sym4 
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Introduction 


A macro is a sequence of instructions that may be automatically inserted in the 
assembly source text by encoding a single instruction — the macro call. The macro 
definition is written only once and can be called any number of times. It can contain 
parameters that can be changed for each call. The macto facility simplifies the 
coding of programs, reduces the chance of user error, and makes programs easier to 
understand, If a macro function needs to be altered, this can be done by changing 
the source code in only one location, the macro definition. 


A macro definition consists of three parts: a heading, a body, and a terminator. This 
definition must precede any call to the macro. 


A macro can be redefined at any place in the program; the most recent definition is 
used when the macro is called. A standard assembler mnemonic (e.g., OR) can also 
be redefined by defining a macro with the name OR. In this case, all subsequent 
uses of the OR instruction in the program will cause the macro to be expanded. 


Calling a Macro 


The syntax for calling a macro is as follows: 
(label] name { .qualifier|- parameter|,parameter).. : 


where: 

label Assigned the current program counter value to label. 

name Specifies the name of the macro. This name should 
have been defined by the MACRO directive or an 
efror message will be generated. 

qualifier An optional qualifier that is passed to the macro as 
parameter \0. 

parameter _ Specifies constants, symbols, expressions, character 


strings, or any other text separated by commas. The 
maximum number of parameters supported in a 
macro call is 35. 
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A macro can be called by encoding the macro name in the operation field of the 
Statement. 


The parameters in the macro call are actual parameters and their names can be 
different from the formal parameters used in the macro definition. The actual 
parameters will be substituted for the formal parameters in the order in which they 
are written. Commas can be used to reserve a parameter position. In this case, the 
parameter will be null (i.e., contain no actual characters). The formal parameter 
corresponding to a null actual parameter is simply removed during macro 
expansion. Any parameters not specified will be null. The parameter list is 
terminated by a blank, tab, new-line, or semicolon. 


All actual parameters are passed as character strings into the macro definition 
statements. Thus, symbols are passed by name and not by value. In other words, if 
a symbol’s value is changed in a macro expansion, it will also have the new value 
after the expansion. Thus, SET directives within a macro body can alter the value 
of parameters passed to the macro. 


The angle brackets (< >) delimit actual parameters that can contain other delimiters. 
When the left bracket is the first character of any parameter, all characters between 
it and the matching right bracket are considered part of that parameter. The outer 
brackets are removed when the parameter is substituted in a line. Angle brackets can 
be nested for use within nested macro calls. 


The brackets are the only way to pass a parameter that contains a blank, comma, or 
other delimiter. For example, to use the instruction ROL #1,D1 as an actual 
parameter would require placing <ROL #1,D1> in the actual parameter list. A null 
parameter can consist of the angle brackets with no intervening characters, but the 
characters < and > cannot be passed as parameters and the parameter \0 cannot 
contain angle brackets. 


The operator double equal sign (==), pronounced exists, can be used to determine 
whether a parameter is present or not in the macro call. This operator returns a true 
value (all ones) if any operand follows the == and a false value (all zeros) otherwise. 


The == operator can be used in combination with other operators. It takes as its 
argument the entire remainder of the line, up to a comment delimiter, if present, or 
to the end of the line. Therefore, using other operators to the right of == is useless. 
If a comment field follows an == operator, it must be prefixed by a semicolon (;). 
A parameter consisting entirely of blank characters will test null. 
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2 Examples 


An example of a macro call and its expansion is shown below: 


GET MACRO W,Y,Z #macro definition 
MOVE #W,DS 
ROL #1,D5 
Y 
Z JMP \4 
ADD.\O0 #5,D0 
ENDM 


LOOP GET.B 200,<BRA DATA>,ENTRY,MAIN ;macro call 
JMP FIRST 


Loop GET.B 200,<BRA DATA>,ENTRY,MAIN ;macro expansion 


+ MOVE #200,D5 
+ ROL #1,D5 

+ BRA DATA 
+ENTRY IMP MAIN 

+ ADD.B #5,D0 


JMP FIRST 


Note that expanded code is marked with plus signs for description purposes only in 
the documentation. 


~. MSET MACRO DATA, MEM 
IFNE ==MEM 
MOVE #DATA, MEM 
ELSEC 
MOVE #DATA, (Al) 
ENDM 


The above example checks whether the second parameter MEM is present. The == 
operator determines if there is a value for mem, or if it is null. The 1FNE instruction 
checks for a non-zero value. Therefore, if m=m has a non-zero value, the following 
Mov#E instruction is executed; if mem has a zero value (i.c., the parameter is not 


present in the macro call), the Move instruction following the ELSEc instruction is 
executed. 
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NARG Symbol! 


Macros 


The special symbol NARG is used to represent the number of non-null actual 
parameters passed to the macro as opposed to the number of formal parameters in 
the macro definition. NARG is considered to be zero outside of a macro definition. 
It is typically used when generating tables within macros, along with conditional 


assembly statements. 
Example: 


GEN MACRO 
IFNE 
Dc.B 
GEN 
ENDC 
ENDM 

ADD1 EQU 

ADD2 EQU 
GEN 


*Macro expansion: 
IF 

TEO2 DC.B 
GEN 
IF 

0301 DC.B 
GEN 
IF 
DC.B 
GEN 
ENDC 
ENDC 
ENDC 


P1,P2,P3 
NARG 
P1,NARG 
P2,P3 


$7F 
3 
ADD1, ADD2 


NARG 
ADD1, NARG 
ADD2, 
NARG 
ADD2, NARG 


#Macro Cail 


; (Value of NARG)} 


sNot executed 


JNot. executed 


Note that the value of NARG is not displayed in the expansion any more than the 
value of any other symbol is displayed there. In the example above, the pc.B 
directive is used so that the value of NARG can be seen. 
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Macro Directives 


A macro is referenced by using its name in the operation (opcode) field of a source 
statement. Formal arguments can be defined on the call line and then referenced in 
the body of the macro. 


The following pages describe the macro directives. An alphabetical listing of the 
directives is provided in Table 7-1. 


Table 7-1. Listing of Macro Directives 


Directive Function 


ENDM Terminates Macro Definition 


LOCAL Defines Local Symbols 
MACRO Enters Macro Definition 


Exits Macro 


O 


NL ‘ 
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ENDM — Terminates Macro Definition 
Syntax 
(label) ENDM 
Description 


label Specifies the symbolic address of the first byte of memory 
following the inserted macro. If label has embedded 
parameters, it must be placed on the preceding line. 


The ENDM directive terminates the macro definition. During a macro definition, 
an ENDM must be found before another MACRO directive can be used. An END 
directive that is found during a macro definition will terminate the definition as well 
as the assembly. 


Labels with embedded parameters are not allowed on the same line as the ENDM 
directive. The label can be placed on the line preceding the ENDM directive for the 
desired effect. 


. a 
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LOCAL 


Ce eee ene ee ee eee enemas eee ccc sss csc see ee TT a ESET 


LOCAL — Defines Local Symbol 


Syntax 


LOCAL symbol[,symbol)... 


Description 


symbol Defines a symbol local to this macro. 


All labels, including those within macros, are global (i.e., known to the entire 
program). A macro containing a label that is called more than once will cause a 
duplicate label error to be generated. To avoid this problem, you can declare labels 
within macros to be local to the macro. Each time the macro is called, the assembler 
assigns each local symbol a system-generated unique symbol of the form ??nnnn. 
Thus, the first local symbol will be 720001, the second 770002, etc. The assembler 
does not start at 720001 for each macro but increases the count for each local 
symbol encountered. The maximum number of local symbols allowed inside a 


. macro definition is 90. 


The symbols defined in this directive are treated like formal macro parameters and 
can therefore be used in the operand field of instructions. The operand field of the 
LOCAL directive cannot contain any formal parameters defined on the MACRO 
directive line. As many LOCAL directives as necessary can be included within a 
macro definition, but they must occur immediately after the MACRO directive and 
before the first line of the macro body including any comment lines. LOCAL 
directives that appear outside a macro definition will generate an error. 


For, compatibility with existing code, the assembler will also recognize the . 
Motorola method of declaring local symbols. The string \@ denotes the presence of 
a local symbol. The full name of the symbol is formed by concatenating \@ with 
any: adjacent symbol(s) (e.g., DON\@T counts as one local symbol). The total 
length of a symbol formed in this way should not exceed 127 characters, or the 
assembler cannot resolve it correctly. At macro expansion time, the entire local 
symbol is replaced by a symbol of the form ??nn, just like named local symbols. 
This form can be mixed with named local symbols without conflict although this is 
not recommended. 


Local symbols declared by the \@ construction cannot be present in a LOCAL 
statement but are recognized as they appear. The \@ format is not recommended for 
new code as it obscures the meaning of the macro definition without adding clarity 
to the expansion. 
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Example 
WAIT MACRO 
LOCAL 
LAB2\@ MOVE.B 
LAB1 DBLE 
| ENDM 
| +270002 MOVE .B 
+220001 DBLE 
+220004 MOVE .B 
+720003 DBLE 


purposes only in the documentation. 


TIME 
LAB1 
#TIME,DO 
DO, LAB2\@ 


#5,D0 

Da, 770002 
$FF,DO 
DO, 770004 


Macros 


;macro definition 


;first call 


‘ swith TIME=5 


saecond call 
swith TIME<$FF 


In the example above, expanded code is marked with plus signs for description 


O 
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MACRO 


MACRO — Enters Macro Definition 


Syntax 
label MACRO parameter|, parameter}... 
(label) ENDM 


Description 


label Specifies the macro name and must not end in .B, .W, .L, or 
, .S because these strings will be interpreted as a qualifier on 
a shorter name when the macro is invoked later, and the 
correct macro will not be referenced. Other than this 
condition, the macro name can be any legal symbol and it 
can be the same as other program-defined symbols since it 
bas meaning only in the operation field. For example, TAB 
could be the name of a symbol as well as a macro, 


parameter Specifies a symbol known only to the macro definition; it 
can be used as a regular symbol outside the macro. Multiple 
parameters must be separated by commas. — 


The first line of code following the MACRO directive that is not a LOCAL macro 
directive is the start of the macro body. No statements in a macro definition are 
assembled at definition time. They are simply stored internally until called, at which 
time they are inserted in the source code at the position of the macro call. During a 
macro ¢all, an etror will be generated if another macro is defined within a macro, 


If a macro name is identical to a machine instruction or an assembler directive, the 
Mnemonic is redefined by the macro. Once a mnemonic has been redefined as a 
macro, there is no way of returning that name to a standard instruction mnemonic. 
A macro name can also be redefined as a new macro with a new body. 


Unnamed (i.e., null) formal parameters are not allowed if they are followed by any 
named parameters. 


Example 


XYZ MACRO ,, PARAM 


The above example is illegal because the null formal parameter is followed by 
PARAM3 Which is a named parameter. This means that unnamed parameters must 
either come after all named parameters on the macro definition line or must be 
assigned a dummy name. Dummy formal parameters can be specified in the order 
in which they will occur on the macro call. 
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The name of a formal parameter specified on the MACRO directive can appear 
within the macro body in any field. If a parameter exists, it is marked, and the real 
corresponding parameter from the macro call will be substituted when the macro is 
called. Parameters.are not recognized in a comment statement or in the comment 
field of a statement, provided the comment field is prefixed by a semicolon (;). 


Unnamed parameters and named parameters can be referenced with the Motorola 
backslash notation (\n where x is a non-negative integer) in terms of the parameter’s 
position on the call line. Parameter \0 is the qualifier (extension) of the macro call 
and can appear only as a qualifier on opcodes in the macro body. (This is the only 
format in which this qualifier can be referenced). Parameters \1,\2,...\9,\A,...\Z are 
the first, second, etc. real parameters on the macro call line. 


Macro parameters will be expanded in a quoted string. But, if the quoted string is 
preceded by A for ASCII or an E for EBCDIC, macro parameters are not expanded 
within the string. This extension permits backslashes and formal parameter names 


to appear as a string. 


When referring to macro parameters in the macro body, you can precede the macro 
parameter with &&. This lets you embed the parameter in a string. 


Example 


MAC1 MACRO P1 # Macro definition 
L&&P1 MOVE DO,D1 ; Create label using parameter 
ENDM Macro terminator 


~ 


. MAC1L XX Macro call 
-1 00000000 3200 Lxx MOVE DO,D1 ; Create label using parameter 
END 


a 


RAone wn er 


Microtec Research, Inc, 


Macros MEXIT 


MEXIT — Exits Macro 
Syntax 
(label) MEXIT 
Description 
label Assigns the address of the current location counter to label. 


The MEXIT directive is an alternate method for terminating a macro expansion. 
During a macro expansion, an MEXIT directive causes expansion of the current 
macro to stop and all code between the MEXIT and the ENDM for this macro to 
be ignored. If macros are nested, MEXIT causes code generation to return to the 
previous level of macro expansion. Note that either MEXIT or ENDM terminates 
a macro expansion, but only ENDM terminates a macro definition. 


Example 


In the following example, the code following MEXIT will not be assembled if pata 
is not zero. 


STORE MACRO DATA 


IF DATA 
MEXIT 
ENDC 


ENDM 
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introduction 


ASM68K includes several high-level language constructs similar to those of C and 
Pascal which control run-time loops and conditional execution. These constructs 
are provided to increase the ease with which you write code in assembly language 
while retaining most of the size and speed advantages inherent in the assembler 


language. 


Structured Control Expressions 


Syntax for the IF, UNTIL, and WHILE statements require a field referred to as a 
structured control expression. This expression has a logical value of true or false 
and is one of the following: 


1. Acondition code (CC, EQ, etc.) enclosed in angle brackets. 


Example: 
<MI> 


This type of structured control expression generates a conditional branch 
instruction (Bcc), which tests the indicated bits of the condition codes, Any 
of the 14 condition codes accepted in the conditional branch instruction 
(Bcc) is legal and should be set previously. The test can be complemented 
to reflect your intent in some constructs. The expression is true if the 
condition code setting described is true. 


2. Two expressions (as defined in Chapter 2, Assembler Language), separated 
by a condition code enclosed in angle brackets (e.g., COUNT <LE> #4). 


This type of structured control expression generates a CMP (compare) 
instruction followed by a conditional branch. If the two expressions do not 
form a legal pair of operands for this instruction, an error will occur when 
the CMP is assembled. The # sign is required on all immediate operands. 


The size of the CMP is controlled by the qualifier on the directive 
containing the structured control expression. It is not always possible to 
produce a single conditional branch that is equivalent in meaning to the 
expression coded. This is further discussed below. 
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3. 


Two structured control expressions, based on the two rules above, separated 
by the keywords AND or OR. These keywords can optionally have one of 
the qualifiers .B, .W, or .L (e.g., COUNT <LE> #4 AND.B <CC>). 


This type of structured control expression generates the code for its left side 
followed by the code for its right side. There are no extra instructions 
generated by AND or OR. The branches are constructed so that the right 
side of AND is not evaluated when the left side is false (the compound 
expression is known to be false), nor is the right side of OR evaluated when 
the left side is true (the compound expression is known to be true). 


Operands may be relocatable expressions. They cannot be complex. This is 
described in more detail under Relocatable Expressions in Chapter 5, Relocation. 
More complex combinations such as COUNT <LE> #4 AND <CC> OR X <GT> 
Y are not legal. At least one space or tab must appear between different parts of a 
Structured control expression. 


The following rules are applied: 


1. 


The size of the CMP (if any) to the left of the AND or OR is taken from the 
qualifier on the directive. 


The size of the CMP (if any) to the right of the AND or OR is taken from 
the qualifier on the AND or OR. 


. A compound expression containing AND is true if and only if the 


expressions on both sides of AND are true, otherwise it is false. 


. A compound expression containing OR is false if and only if the 
- expressions on both sides of OR are false; otherwise, it is true. 


The assembler typically uses the expression preceding a condition code as the left 
operand of CMP, and the expression following the condition code as the right 
operand of CMP. But if this is not a legal combination of operands for CMP, the 
assembler will switch the operands and leave the specified condition code alone. 
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€ , To preserve the meaning of the specified comparison, the assembler will change the 
condition codes as shown in Table 8-1. 


Table 8-1: Conditional Code Comparisons 
Condition Code New Condition 


Equivalent. 
Equivalent. 
Equivalent. 
Equivalent. 
Equivalent. 


Equivalent. 

Marked with a W (warning) flag on the 
F assembly listing when they are not equivalent. 

Marked with a W (warning) flag on the 

assembly listing when they are not equivalent. 

Marked with a W (warning) flag on the 

assembly listing when they are not equivalent. 


The conversions of VC to VC, and VS to VS, fail when the result of the comparison 

is the largest negative number representable in the operation size ($80, $8000, or 

CY $80000000). The conversion of PL to MI or vice versa fails in the same case and 

ee also when the result of the comparison is 0. It is recommended that such flagged 
expressions be recoded to express your intent. 
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The assembler may generate local labels to handle branch instructions. These labels 
will start with two question marks (??). These labels will not show up in the symbol 
table unless OPT G is used. 


Example: 
Line Address 
1 
2 OPT G 
3 
4 FOR.B Dl = #1 TO #10 DO.S 
4.1 Q0000000 123c 0001 MOVE.B #1,Di ;>> FOR << 
4.2 00000004 6002 BRA.S ?70001 ;>> FOR << 
4.3 00000006 5201 720002 ADD.B #1,D1 ;>> FOR << 
4.4 00000008 0CO1 000A 270001 CMP.B #10,D1 ;>> FOR << 
4.5 0000000C 6804 BGT.S 2770004 ;>> FOR << 
5 OODDO000E 34¢1 MOVE.W D1, (A2)+ 
6 ENDF 
6.1 00000010 60F4 ; 720003 BRA ?70002 ;>> ENDF << 
6.2 2270004 ;>> ENDF << 
7 END 

Symbol Table 
Label Value 


220001 0:00000008 
220002 0:00000006 
270003 0:00000010 
220004 0:00000012 


Specific registers or memory locations are not predefined to hold the loop counts or 
values to be compared for the loop end conditions. At assembly time, you have 
control over which registers and memory locations are used. This is accomplished 
through operands specified for the constructs. 


Unlike most high-level languages, there is no restriction on overwriting the loop 
counter, loop increment variable, or either of the loop bounds for the loop. When 
writing code for the loop body, special care should be taken not to alter these 
variables. 


A SET variable cannot effectively be used as a loop index since SETs only affect 
variable values at assembly-time. 
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Structured Control Directives 


Each of the structured control directives generates one or more assembly language 
instructions, which typically includes compare and branch instructions. These 
statements are used to control looping or conditional execution at runtime, not at 
assembly time. Table 8-2 lists the structured control directives. 

Table 8-2. Alphabetical Listing of the Structured Control Directives 


Directive Function 


Exits Loop Prematurely 
Specifies For Loop 


Specifies If-Else Construct 
Proceeds to Next Iteration of Loop 
Specifies Repeat Loop 

Specifies While Loop 


The IF structure directive should not be confused with the IF conditional assembly 
directive. At assembly-time, each structure directive is translated into the 
appropriate assembly language code that will be executed at run-time. Conditional 

assembly directives do not generate code, They only control what will and will not 
be assembled. 


1. Microtec Research has extended the Motorola contro! directives to add two directives that alter the flow 
of loop constructs, 


2. The following keywords can be used within this construct: AND, BY, DO, DOWNTO, OR, THEN, and 
TO. 
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Structured Control Statements 


BREAK — Exits Loop Prematurely 


84 


Syntax 
BREAK [ . extent] 
Description 


extent Specifies size (.S or .L) of the forward branch. If not present, 
the size of the forward branch is determined by the current 
setting of the B option (OPT BRL or OPT BRS). 


The BREAK ditective provides a convenient way to exit a FOR, WHILE, or 
REPEAT loop before the condition terminating the loop becomes true. BREAK 
generates a jump to the assembler-generated label (not known to you when coding 
the program) that comes immediately after the innermost active loop in which the 
BREAK appears. Since this branch is a forward reference, an extent code .S or .L 
can be attached to the BREAK directive to force either a short or long forward 
branch. . 


if a BREAK directive appears outside of a FOR-ENDF, WHILE-ENDW,, or 
REPEAT-UNTIL loop, an opcode error is reported and no code is generated. Note 
that BREAK is not allowed in an IF construct. 
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Structured Controf Statements FOR ... ENDF 


FOR. .. ENDF — Loops Based on Counter 


Syntax 


Description 


FOR{ .qualifier] op] = op2 {TO | DOWNTO} op3 [BY op4] DO[.extent] 
loop_body 

ENDF 

qualifier Applies this size qualifier to MOVE, CMP, ADD, or SUB 
instructions within the loop. Valid values for qualifier are: B, 
W, or L. 

opl Specifies the loop counter, which must be an expression that 
is legal as the right side of a MOVE instruction (typically a 
label or a register). 

op2 Specifies initial value of the loop counter. 

op3 Specifies final value of the loop counter. 

op4 Increments (for To) or decrements (for DownTo) loop counter 
by this value. If op4 is not specified, the loop is incremented 
or decremented by 1. > 

extent Specifies size of branch (.S or .L). If not present, the size of 
the forward branch is determined by the current setting of the 
B option (OPT BRL or OPT BRS). 

loop _body Specifies one or more statements. Any structured control 


statements must be properly nested. 


This statement is an iterated loop, like the FOR loop of Pascal or C and the DO loop 
of FORTRAN. The loop is executed until op/ is greater than op3 for to (opl less 
than op3 for pownTo), which means that it can be executed zero times if op! is 
greater than op3 (for To) when the loop is entered. 


The FOR...ENDF loop generates a MOVE, a CMP, and either an ADD or SUB, 
plus various conditional and unconditional branches. The CMP is performed at the 
top of the loop, which means that the following conditional branch out of the loop 
is a forward reference. 


The generated CMP instruction is executed once, even if the values of op/ and op3 
are such that the body of the loop is executed zero times. Upon exit from the loop, 
op! will contain the last value to which it was incremented/ decremented (which 
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will be outside the range of the loop bounds) and the condition codes will reflect the Y 
failing CMP. Unlike most high-level languages, there is no restriction on storing 

into the loop counter, loop increment, or either of the loop bounds within the loop 

(although doing so is error-prone). 


Spaces or tabs are required as separators (including around an equal sign). 


Fields op/ through op4 are used as instruction operands just as they appear. If a 
legal instruction is not produced, errors will occur when the generated instruction is 
assembled. Any immediate data must have # signs attached. If any operand is an A 
register, the qualifier on FOR must not be .B (byte). The default increment size of 
1 is usually inappropriate when branching through word or long-sized data. 


Examples 
FOR.B Dl = #1 TO #10 DO.S 
MOVE.W D1, (A2)+ 
ENDE 
FOR.L Al = #HIGHADD DOWNTO #LOWADD BY #4 DO 


MOVE.L (Al), -(A2) 
ENDF 


O 


O 
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IF... THEN... ELSE... ENDI — Performs Conditional Execution 


Syntax 


IF[.qualifier) <structured_control_expression> THEN | .extent] 
then_part 

[ ELSE[ .extent] 
else_part } 

ENDI 


Description 


qualifier Applies size qualifier to the structured_control_expression. 
Valid values for qualifier are: B, W, or L. 


structured_control_expression 
Specifies an expression that evaluates to a logical value of 
true or false. See the Structured Control Expressions section 
in this chapter for more information. Angie brackets around 
structured_control_expression are required. 


extent Specifies size (.S or .L) of the conditional branch. If not 
present, the size of the forward branch is determined by the 
current setting of the B option (OPT BRL or OPT BRS). 


then_part Specifies a set of statements that will be executed if the 
structured_control_expression evaluates to true. 


else_part Specifies a set of statements that will be executed if the 
Structured_control_expression evaluates to false. 


Only the statements in the then_part will be executed if the structured-control- 
expression is true, and only the statements in the (optional) else_part will be 
executed if the structured_control_expression is false. 


The qualifier on the IF statement is used when generating code for the 
structured_control_expression. The extent code on THEN, which can be .S or -L, 
is used when generating the conditional branch from the test (at IF) to the else_part. 
Similarly, the extent code on ELSE is used when generating the unconditional 
branch from the end of the then_part to the end of the else_part. 


Examples 


IF.B (Al) <LT> #0 THEN.S 
MOVE.B 0, (A1) 

ELSE.S 

ADD.B #1, (Ai) 

ENDI 
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. THEN... ELSE... ENDI Structured Control Statements 


This example shows mixed conditional assembly and structured 
syntax IFs. 
; As you see, the combination is difficult to understand 


sometimes. 
IF VARIABLE + conditional 
IF VARIABLE <NE> #0 THEN.S * structured 
MOVE #0, VARIABLE 
ELSE.S # unambiguously structured 
* because of .S, no W flag is 
+ given 
JSR ERROR 
ELSE 7; conditional, because structured is illegal 
IF VARIABLE <EQ> #0 THEN.S # structured 
MOVE #1, VARIABLE 
ENDC ¢ conditional 


ENDI structured- terminates 


? whichever of the preceding 
structured IF’s was assembled 


™~ 


~ 
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NEXT — Proceeds to Next Loop Iteration 
Syntax 
NEXT [ . extent] 
Description 


extent Specifies size (.S or .L) of the forward branch. If not present, 
the size of the forward branch is determined by the current 
setting of the B option (OPT BRL or OPT BRS). 


The NEXT directive provides a convenient way to proceed to the next iteration of 
a FOR, WHILE, or REPEAT loop. NEXT generates a jump to the assembler- 
generated label at the bottom of the innermost active loop in which the NEXT 
directive appears. Since this branch is a forward reference, an extent code .S or .L 
can be attached to the NEXT directive to force either a short or long forward 
branch. 


If a NEXT directive appears outside of a FOR..ENDF, WHILE...ENDW, or 
REPEAT...UNTIL loop, an opcode error is reported and no code is generated. 
Note that NEXT is not allowed in an IF construct. 
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REPEAT ... UNTIL — Loops Until Condition Not True re) 


Syntax 
REPEAT 
loop_body 
UNTIL[ .qualifier] <structured_control_expression> 
Description 
qualifier Applies size qualifier to the structured_control_expression. 


loop_body Specifies one or more statements that will be executed until 
the structured_control_expression evaluates to true. Any 
structured control statements must be properly nested. 


structured _control_expression 
Specifies an expression that evaluates to a logical value of 
true or false. See the Structured Control Expressions section 
in this chapter for more information. Angle brackets around 
structured_control_expression are required. 


The test is placed at the end of the loop so that loop_body is executed once even if 
structured_control_expression is true upon entry to the loop. The loop is executed ( ) 
until structured_control_expression becomes true. 


The REPEAT generates only a label, and UNTIL generates code for 
structured_control_expression. Since all branches involved are backwards, there is 
no need for an extent field. A comment field on UNTIL must be delimited by a 
semicolon or exclamation point so the assembler will know to stop parsing 
structured_control_ expression. 


| Examples 


REPEAT 
MOVE.L #-1, (Al)}+ 
MOVE.L #0, (A1)+ 
UNTIL.L Al <GE> #SFF8000 


ANDI #$FE,CCR ; clear Carry flag 
REPEAT # this infinite loop might be used 
UNTIL <cS> # while awaiting an external interrupt 
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” WHILE ... ENDW — Loops While Condition True 
Syntax 
WRILE[. qualifier] <structured_control_expression> DO[ .extent] 
loop_body 
ENDW 
Description 
qualifier Applies size qualifier to the structured_control_expression. 


structured_contral_expression 
Specifies an expression that evaluates to a logical value of 
true or false. See the Structured Control Expressions section 
in this chapter for more information. Angle brackets around 
structured_control_expression are required. 


extent Specifies size (.S or .L) of the conditional branch. If not 
present, the size of the forward branch is determined by the 
current setting of the B option (OPT BRL or OPT BRS). 


The loop_body is repeated as long as structured_control_expression remains true. 
* If it is false upon loop entry, then the loop body is not executed, but the CMP test 
is executed once and the condition codes will reflect this. 


The extent field of the DO is applied to the conditional branch from the test out of 
the loop, a forward reference. 


Examples 


WHILE Al <NE> #0 DO.S 
MOVE #0, (Al)- 
ENDW 


WHILE.L #3 <LT> DO AND.L #5 <LT> D1 DO.S 
JSR RETRY 
IF.L #5 <LT> Dl THEN.S 
ADD.L #1,D1 
ELSE.S 
MOVE.L #0,D1 
ADD.L #1,D0 
ENDI 
ENDW 


'~ 
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Structured Directive Nesting 


Structured directives can be nested to create multi-level control structures subject 


to one rule: A directive that begins a new control structure in an inner loop must 
have a corresponding directive that terminates the control structure in the same 
inner loop. 


The assembler keeps track of structured control directives to ensure that they are 
nested properly. The maximum nesting level is 64. This process is totally 
independent of the assembly-time macro stack and conditional assembly stack. It is 
possible for the beginning of a structured control loop to be inside a conditional 
assembly or a macro expansion. The directive ending the structured control loop 
must be specified, but it need not be within the conditional assembly or macro 
expansion. 


An incorrectly nested control directive is flagged with an O (opcode) error and 
ignored by the assembler. If a terminating directive is omitted, an undefined label 
(U) error will follow the control directive beginning the high level construct. 


An example of legal nesting is shown below. 
Example: 


REPEAT 
MOVE.B (Al) +,NEXT_CHAR 
IF.B #CR <EQ> NEXT_CHAR TREN,S 
BREAK .S 
ELSE.S 
IF.B #BLANK <EQ> NEXT CHAR THEN.S ; skip blanks 
NEXT.S 
ELSE. S' 
MOVE.B NEXT CHAR, (A2) + 
IF.L A2 <GT> #120 THEN.S 
JSR ERROR 


fetch character 
done if carriage return 


7 


copy character into buffer 


™e 


UNTIL Al <GT> #120 ; Jump here on NEXT 
RTS # Jump here on BREAK 


Structured Directive Listings 


The code generated by structured control directives is shown in the same way ona 
listing as macro expansions. The code is marked with plus signs (+) and is not 
shown if the M or MEX option is turned off. 
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Introduction 


As previously stated, the ASM68K Assembler uses two passes. During the first 
pass, macros are expanded, labels are examined and placed into the symbol table, 
opcodes and directives are decoded, and statement byte lengths are determined so 
the assembly program counter can be updated. 


During the second pass, the object code is generated, symbolic addresses are 
resolved, and a listing and output object module are produced. Errors detected 
during the assembly process will be displayed on the output listing with a 
cumulative error count. 


At the end of the assembly process, a symbol table or cross-reference table can be 
generated. 


Assembler Listing 


During pass two of the assembly process, a program listing is produced. The listing 
displays all information pertaining to the assembled program — both assembled 
data and your original source statements. 


The main purpose of the listing is to convey all pertinent information about the 


assembled program, the memory addresses, and their values. It can be used as a 


documentation tool by including comments and remarks that describe the function 
of the particular program section. The link module, also produced during pass two, 
contains the object code address and value information in computer-readable 
format. 


A sample listing is provided in Figure 9-1. Refer to the following points in order to 
examine and understand the listing. 


1. The page headings on this sample show the time and date of the program 
run. This information might not be present in some installations. 


2. The line tided Command line: specifies the command line used to invoke 
the assembler. 
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. The source listing contains the columns titled Line and Address. 


The Line column contains decimal numbers that are associated with the 
listing source lines. These numbers are referred to in the cross-reference 
table. The numbers can include periods (.) separating the digits. These 
periods provide a distinction between nesting levels of included or macro 
expanded code. 


The Address column contains a value that represents the first memory 
address of any object code generated by’ this statement or the value of an 
EQU, SET, or FAIL directive. ? 


4, Tothe right of the address are up to three words of object code generated by 
the assembly language source statement. Additional words of object code 
are shown on subsequent lines. The first hexadecimal number represents 
one word of data to be stored in the memory address and the memory 
address plus one. If there are additional words, they will be stored in 
subsequent memory locations. 


5. To the right of the data words are the assembler relocation flags: 


R __ Relocatable operand 
E External operand 
c Complex and relocatable operand ( ) 


If one operand is relocatable and another external, an £ will be displayed. 


6. Original source statements are reproduced to the right of the above 
‘information, Macro expansions and code generated by the structured-syntax 
directives are preceded with a plus (+) sign. 


7. A symbol table or cross-reference table is generated at the end of the 
assembly listing. The table lists all symbols defined in alphabetical order 
along with the section in which they were defined as well as their final 
absolute values. Line numbers in which the labels occur are listed under 


References. 


In the sample listing, there are no errors or wamings. However, if the assembler 
detects error conditions during the assembly process, a line titled ERRoR will contain 
error code(s) describing the errors in the associated line of source code. Also, at the 
end of the listing, the assembler prints the message Errors: mn, Warnings: mm. 
Warnings are represented by a WARNING flag. Errors are represented by an ERROR 


The assembler substitutes two words of NOP’s when it cannot translate a particular 
opcode and so provides room for patching the program. An explanation of the 
individual assembler errors is in Appendix B, Assembler Error Messages. 
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Cross Reference Table Format 


The cross-reference option is turned off by default. To tum it on, use OPT CRE. 
To turn it off again, use OPT -CRE. The assembler will produce either a cross- 
reference table or a symbol table, not both. The cross-reference table will be 
produced only if OPT CRE has been specified. Otherwise, a symbol table will be 


produced. 


References can be accumulated for selected portions of the program by turning the 
cross-reference option on and off at the respective places in the program. However, 
to obtain the cross-reference listing, the option must be turned on before the END 
directive. Typically, the OPT CRE directive will be one of the first statements in 
the source program and will never be tured off. 


An example of the cross-reference output is shown on the sample listing at the end 
of this chapter. Refer to the following points in order to examine and understand the 
cross-reference table format. 


8. All user-defined symbols in the program are listed under the heading 
Label, 


9. The symbol values are listed under value. Any flag to the left of the values 
indicate the relocation type of the symbols. 


10. Under References, a line number preceded by a minus (-) sign indicates 
that the symbol! was defined on that line. Line numbers not preceded by a 
minus sign indicate a reference to a symbol. If no line numbers appear, the 
symbol is the internal system symbol NARG. Note that for SET symbols 
or for multiply defined symbols, more than one definition can appear for 
the symbol. 


Section names, macro names, and the module name do not appear in the symbol 
table listing. 
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' Sample Program Listing 


66026168 
81008808 4E71 


eagnee88 4E71 


baBae8e8 4E71 


Assembier Listings 


Fri Aug 23 17:12:35 1991 Page 1 


FERERETRS ERA EAEA ED ESAS RENEE E SENSE ERE EEE SEER EERE EER ES 
* 

* Sample Standard 58882 Family Testcase 

z 


SESE EREASAESEREA CAAA SKSHARESKA KSEE KASEMEEAEEREKES 


bd 68888 ASSEMBLER SAMPLE TEST CASE 
LLEN 97 
PLEN 48 


OPT CRE 3; Turn on cross reference 


= 


*DEFINE SOME SYMBOLS FOR LATER USE 
* 


ORG $108 
AVAL DS 4 

ORG SEFFFFF 
AVALHI NOP 


3Absolute symbot 


;Absolute symbol requiring 
j 32 bits 
j;Note rounding of location 
3; counter to even address 
SECT SEC1 
NOP jRetocatable symbol in 

3 same section 
SECT SEC2 
Nop ;Relocatabie symbol) in 
3 different section 
;Back to first relocatable 
3 section 
XREF EVAL jExternal reference 
INCLUDE incli.sre ;Test include directive 


SECTION SEC1 


} This 1s a sample include file 


, 

Z i 

*Aliow errorless assembly of 68918 instructions 
CHIP 68818 


Figure 9-1. Sample Assembly Listing 
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Microtec Research, Inc. 


Microtec Research ASMEB8K 


Line Address 


Version 6.8 


geageee2(Ga38 BOFF 8108) 
GBA8B888 BASC BEFF 
@eeegeec B65 2718 
68880818 8B7C BBFF 


68080014 


8898 


9808 A7FE 


06980014 618A abs 


gaae@asic 
baB6882e 


8118 
6158 


8888822 B18A BABA 


90080826 
@eee0928 
eaaaee2A 
@aaaBe2E 
@ga8Be34 
gaaasesB 
eean88e3C 
aB8884a 


6aa8084A 
aage804E 
68888852 
8888856 
aaea8e8esc 
oepAaeEs 
66988864 


8198 
6108 
8288 
6238 
8230 
8248 
8270 
a2B89 
aeee 
8388 
407 
6441 
@49F 
6628 
6648 
4679 
9288 


0041 
GOFF 6188 


8388 SC4B 
OFF 

GG64 

SGFF 8686 E 


Fei dug 23 17:12:35 1991 
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Page 2 


C.1 bit maniputation, MOVEP, MOVES, 
IMMMEOTATE INSTRUCTIONS 


ORI .B 
ORI.B 
ORI.W 
ORI 
ORT.L 
MOVEP 
BIST 
BCHG 
MOVEP 
BCLR 
BSET 
ANDI .B 
ANDI.B 
ANDI .B 
ANDI 
ANDI 
ANDI .L 


MOVEP .W 
SUBI.B 
SUBI 
SUBI.L 
ADDI .B 
ADDI 
ADDI.¥ 


END 


#255, AVAL 
#255, COR 
#10080, ~(AS) 
#255,SR 
#43008, (AB)+ 


#255, CCR 

#28680 ,08 
#255, SR 
#SPAFEFEFE EVAL 


D1, 18(AB) 
#255 ,D7 
4#4996,01 
#49800, (A7)+ 
#255,-(Aa) 
#100,08 
#255, EVAL 


Figure 9-1. Sample Assembly Listing (cont.) 
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Cross Reference 


Labet Value 


AVAL 6880188 
AVALHI @16e@8888 
EVAL External 
RVAL1  SEC1:8888daa8 
RVAL2 SEC2:a8e80000 


References 


-14 29.11 29.23 
-16 

28 29.27 29.4 
-21 

-24 


O 


Figure 9-1. Sample Assembly Listing (cont.) 
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The Object Module 


During pass two of processing, the assembler produces a relocatable object module. 
The object module is a file that consists of variable length records in the Microtec 
Research binary IEEE-695 format. The object module contains specifications for 
loading the memory of the target microprocessor and provides the necessary 
linkage information required to link object modules together. 


Relocatabie object modules can be loaded into the linker and converted to a single 
absolute program in one of three different formats (Motorola S-Record, IEEE-695, 
or HP-OMF). The absolute object module can then be loaded into a development 
system, used to program a PROM, or read into the simulator. 
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This chapter describes the LNK68K Linker that accompanies the ASM68K 
Relocatable Macro Assembler. Many programs are too long to conveniently 
assemble as a single module. To avoid long assembly times or to reduce the 
required size of the assembler symbol table, long programs can be subdivided into 
smaller modules, assembled separately, and linked together by the linker program. 
After the separate program modules are linked and loaded by this program, the 
output module functions as if it had been generated by a single assembly. The 
primary functions of the linker are to: 


1. Resolve external references between modules and check for undefined 
references (linking). 


2. Adjust all relocatable addresses to the proper absolute addresses (loading). 


3. Output the final absolute object module(s). Absolute output can be produced 
in Motorola hexadecimal S-Record format, in Microtec Research IEEE-695 
format (default), or in Hewlett-Packard HP-OMF format. 


The linker can be used to combine several independently-assembled relocatable 
object modules into a single absolute or relocatable object module. 


Multiple relocatable object modules can be combined into a single relocatable 
object module suitable for later re-linking with other modules. This is known as 
incremental linking. In an incremental link, external references are resolved 
whenever possible. No section address assignment or resolution of relocatable 
references is performed. 


When an absolute load is performed, relocatable addresses are transformed into 
absolute addresses, external references between modules are resolved, and the final 
absolute symbol value is substituted for each external symbol reference. The linker 
lets you specify the program section addresses and external definitions. It also lets 
you assign the final load address and section loading order. 
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Linker Operation 


The 68000 linker supports the following features: 


Absolute output in Motorola hexadecimal S-Record format, in Microtec 
Research IEEE-695 absolute format (default), or in Hewlett-Packard 
64000 format 

Independently-specified relocatable section load addresses 

Specified relocatable section loading order 

Incremental linking 

Definition of external symbols at link time 

Values of previously-defined externals changed at link time 

Loading of object modules from a library. The linker will include only 
those modules from a library that are necessary to resolve external 
references. Library modules can also be incrementally linked. 
Inclusion of symbols and line number information in the absolute object 
module for symbolic debugging 

Cross-reference table generation 

Scatter loading 

For better memory utilization, first fit algorithm places object modules 
in memory 

Complex relocation 

A2-A5 address register-relative addressing 

Initializing data from ROM and other locations 

Automatic copying of initialized data values, which can be placed in 


ROM 


Program Sections 


To effectively use the ASM68K Assembler and LNK68K Linker, you must 
understand the various program sections and section load addresses. 


Absolute Section 


10-2 


The absolute section is that part of the assembly program that contains no 
relocatable information but is to be loaded at fixed locations in the user’s memory. 
Absolute code is placed into the output module exactly where specified by the input 
object modules. Note that only those bytes of memory which actually contain data 
are considered to be within the absolute section. Areas skipped by a DS directive, 
for instance, are not stored as data. However, the section size will reflect the area 
resetved by the DS directive. 
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Relocatable Sections 


A relocatable section is one of up to 30,000 general purpose sections which can 
contain both instructions and/or data. Typically, each section is a logically distinct 
part of the total program. Instructions in one section can make references to other 
sections. 


Each section is identified by a symbolic name, The same section name can appear 
in different relocatable object modules. The section, as a whole, refers to code from 
all object modules which is associated with the section name. On occasion, it will 
be necessary to refer to the individual pieces of code from various modules which 
make up a section; these will be called subsections. You can override the default for 
combining sections by the linker with the MERGE or ALIAS linker command. 


In the assembler, sections can be given numbers rather than names. However, the 
assembler translates such numbers into names as described in the chapter called 
Relocation. From the linker’s point of view, all sections are named. 


Each relocatable section has four attributes: 


* common/noncommon 
e short/long 
¢ section type 
¢ section alignment 
Sections containing these types of attributes are described below. For more 


information on relocatable modules using these attributes, refer to Chapter 5, 
Relocation. 


Common Section 


A common section contains variables that can be referenced by each module. All 
common subsections are loaded beginning at the same address providing an 
effective communication area. This is similar to FORTRAN Common. ae length 
of a common section is the size of its largest subsection. 


If more than one input subsection contains code in the same common section, the 
output module will contain all such code even though it can overlap. The reactions 
of various programs which read the output module to this condition are not 
predictable. For this reason, a waming flag is given at assembly time to any code 
produced in a common section. 


Noncommon Section 


A noncommon section is the only type available for code. The subsections of a 
mnoncommon section are loaded into a contiguous block of memory and do not 
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overlap. The size of a noncommon section is the sum of the sizes of all its UY 
subsections plus alignment. 


Short Section 


A short section can be referenced by the absolute short addressing mode and, for 
this reason, it must be loaded into the areas of memory which can be reached by a 
16-bit sign-extended address (see Table 10-1). The target chip can be specified by 
the CHIP command. The linker never puts a short section in an inappropriate area 
of memory. 


Table 10-1. 16-Bit Absolute Address Memory Areas 


Chip Address Range 


68000/10 0 to $7FFF 
$FF8000 to $FFFFFF 


68008 0 to $7FFF 
$F8000 to $FFFFF 


68020/30/40/CPU32 0 to $7FFF 
$FFFF8000 to SFFFFFFFF 


A section is designated as short if any of its subsections are short, or if it appears in YU 
a SORDER directive in the linker commands, 


Long Section 


A long section is a section which is not short and which can be placed anywhere in 
memory. 


Section Type 
There are four types of relocatable sections: 


1. C — Program Code 

2. D—Data 

3. M — Mixed code and data 
4. R—ROMable Data 


The section type attribute has two purposes. First, it can serve as documentation of 
what a section contains. Program code sections generally contain instructions. Data 
sections generally contain read/write data items. ROMable data sections generally 
contain read-only data items. 
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The section type attribute affects the production of HP 64000 symbolic information 
in the asmb_sym (assembler symbol) and link_sym (linker symbol) files. The HP 
64000 file formats define three relocatable sections, PROG, DATA, and COMN 
as well as the absolute section(s) ABS. The section type attribute is used to map the 
various relocatable and absolute sections onto the HP 64000 sections PROG, 
DATA, COMN, and ABS. 


Section Alignment 


The section alignment attribute can be any power of 2. The section alignment 
attribute affects the beginning address of each file’s contribution to a section (i.e., 
subsection). That is, if several files each define a relocatable section named A and 
the alignment for this section is 4, then the beginning address of section A in each 
file will be rounded up to a modulo 4 boundary if necessary. For more information 
on section alignment, see the ALIGN linker command. 


Memory Space Assignment 


You can control the order in which sections are assigned space in memory. You can 
specify the initial address (load address) of any or all sections. By specifying the 
load address, the memory location of subsequent sections that do not have load 
addresses specified are modified, but the order in which sections are assigned space 
is unchanged. Loading need not begin at the base address if SECT and/or 
COMMON commands are used. 


The algorithm used to allocate memory is a three-step procedure as follows: 


1. Allocate absolute sections and sections specified by the SECT and 
COMMON linker commands. 


2. Allocate short sections. 
3. Allocate long sections. 


The order in which short or long sections are assigned memory is as follows: 


1. Any sections listed in ORDER commands (for long sections) or SORDER 
commands (for short sections) in the sequence in which they were named in 
that command. 


2. Any other sections belonging to the group in the sequence in which their 
names were encountered by the linker. 


The linker encounters a section name when it appears in a command that you have 
given or when a module which refers to that section name is loaded with the LOAD 
command. Names appear in relocatable object modules that are produced by the 
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assembler in the sequence in which they appeared in directives in the assembler 
source input. You can use the MERGE command to override the default combining 
of sections by common name. 


Note 


Library relocatable object modules which are not selected for 


inclusion in the absolute object module do not have their section 
names examined by the linker. 


To assign memory to a section, you need to assign it a Ioad address. For those 
sections in which you specified load addresses (in a SECT or COMMON 
directive), nothing more need be done. Otherwise, the following will occur: 


1. The first short section is loaded at the first available space after the base 
address as specified by the BASE command. If no BASE command is 
given, the default base address is 0. 


2. Subsequent short sections are loaded immediately above the preceding 
section, unless this would cause the high end of the section to extend above 
$7FFF, in which case the section is loaded at the lowest address in the short- 
addressable area of high memory (which depends on the target chip). The 
linker will not split a short section between low and high memory. 


3. The first long section is loaded immediately above the short section that is 
most recently loaded into low memory. Caution is required because an 
earlier short section might have been loaded into memory above the most 
recently loaded short section (if a SECT or COMMON command was 
used) which will now overlap the long section. The first long section will be 
loaded at the base address as-specified in item 1 above if there were no short 
sections. 


4. Subsequent long sections start immediately above the preceding long 
section. 


Relocation Types 
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By default, sections are word relocatable. That is, they must begin on an even 
location. If an odd load address is specified, it will be rounded up. You can, 
however, use the PAGE and CPAGE commands to specify that certain sections are 
page relocatable, meaning that their starting address is rounded up to a multiple of 
$100. This page relocatability can be turned on and off between modules, which lets 
you control the relocation type of each subsection. 
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Page relocation is useful for debugging since it means the absolute addresses 
assigned by the linker will match the last two digits of the relocatable addresses 
shown on the assembler listing. 


In the typical load sequence, the linker places contiguously in memory all 
subsections of the first section it assigns, followed immediately by all subsections 
of the second section, etc. There are no extra bytes between the subsections unless 
a subsection contains an odd number of bytes, in which case one byte is left in 
between the subsections in order that the next higher subsection will start on an even 
address. 


If any of the subsections specify page relocation, however, the linker will start that 
subsection at a page boundary to preserve relocation. Whenever any subsection of 
a section is page relocatable, the first subsection in that section starts on a page 
boundary, unless the section has a load address specified. To avoid wasting 
memory, you can always specify section load addresses. If paging is in effect at the 
time the first subsection of a section is loaded with the LOAD command, even a 
specified load address will be rounded up. 


Since all subsections of a common section start at the same location, specifying 
page relocation for any common subsection results in page relocation for the 
section. 


Incremental Linking 


The incremental linking feature lets the linker produce a single relocatable object 
module from assembled relocatable object modules, resolving all external 
references between the modules loaded. Undefined extemal references to other 
modules can still exist in the output object module. These are reported on the link 
map. 


Incremental linking is useful because it lets groups of users easily share relocatable 
object modules for the joint development of code. Long lists of previously-checked 
object modules do not have to be linked with those modules currently under 
development. Only one incrementally-linked module has to be linked, making it 
unnecessary to know all the original module names that are being linked with the 
new code. 


The following example shows incremental linking of four test modules: TEST1, 
TEST2, TEST3, and Test4. In the first part of the example, a normal load is 
performed requiring four load commands. In the second part of the example, three 
of the modules are incrementally linked into TesT123. Then, TEST123 and TEST4 
are linked to produce one absolute output file. 
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Example: U 


TEST .CMD * A command file that consists of four 
* load commands to link four relocatable 
* object modules. 


LOAD TESTI 
LOAD TEST2 
LOAD TEST3 


LOAD TEST4 


TEST. ABS 


The same result could be achieved with the two following load command 
sequences: 


TEST123.CMD is a command file consisting of the following commands: 


LOAD TEST1 
LOAD TEST2 
LOAD TEST3 


' 


TEST123.0BJ 


TEST.CMD is a coramand file that consists of the following commands: QO 


LOAD TEST123.0BI 
LOAD TEST4.OBT 


' 


TEST.ABS 
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Introduction 


The LNK68K Linker reads a sequence of commands from a specified command file 
and/or interpreted command line. The linker combines information from the 
command line with the command file to produce a temporary file from which the 
commands are interpreted. Object modules are read from the location specified with 
the LOAD commands. 


The output of the linker consists of one or more absolute load modules suitable for 


loading into an actual microprocessor. The output module is written to the output 
device in the absolute object module format. 


For information on invoking the linker with a command file, refer to the invocation 
samples in the ASM68K User's Guide. 


Command Syntax 


Commands and command arguments can begin in any column. Command 
arguments must be separated from the command by at least one blank. Comments 
are indicated by an asterisk. 


Numeric command arguments can be represented in the following ways: 


1. Hexadecimal constants can be preceded by a $ (e.g., $LF) in which case they 
need not have a leading zero even if they start with any of the hexadecimal 
characters A through F, Any legal hexadecimal constant can be used, and a 
terminator is not required. 


2. Hexadecimal constants can be terminated by the letter H or the letter X (e.g., 
1FX) in which case any legal hexadecimal constant can be used in the 
command argument. A leading § is legal. 

3. Binary, in which the numeric command argument terminates with a B. 

4. Octal, in which the numeric command argument terminates with an O. 


5. Decimal, in which the numeric command argument terminates with a D. 
This decimal representation is the default. 
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Example: 
The following command file shows numeric command arguments. 


10108 ; binary {A hex) 


sect sectli « 

sect sect2 = 10100 ; octal {208 hex) 
sect sect3 = 1010D ; decimal (3F2 hex) 
sect sect4 = 1010 ; decimal (3F2 hex) 
sect sect5 = 1010H ; hexadecimal (1010 hex) 
sect sect6 = $1000 ; hexadecimal (1000 hex) 


load lod_expres 
end 


The resulting module summary will be as follows: 


MODULE SECTION: START SECTION: END FILE 


lod_expres sectl:0000000A sect1:0000000D lod_expres.o 
sect2:00000208 sect2:0000020B 
sect3:000003F2 sect3:000003F5 
sect4:000003F2 sect4:000003F5 
sect5:00001010 sect5:00001013 
sect6:00001000 secté:00001003 


or’ 


Symbols and section names must follow the syntax mules for symbols given in the 
assembler manual: i.e., they must begin with a letter, a period (.), a question mark 
(2), of an underscore (_). Subsequent characters can be a dollar sign ($) or a 
decimal! digit. ; 

Section names, symbols, and reserved names (e.g., IEEE) are by default case- 
sensitive in the linker command file. The CASE linker command can alter this 
default. The OPT CASE assembler directive specifies that symbols are case- 
sensitive in the assembler. 


Command Position Dependencies 


The linker will process commands in the following order and also handle positional 
dependencies by the following rules: 


1. Preprocessed commands such as INCLUDE are expanded before any 
linker commands are processed. 
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2. Non-position dependent commands are processed next: 


3. Position-dependent commands are processed next: 


CASE should be before any command using names 
j LOWERCASE _ should be before any command using names 
hi UPPERCASE should be before any command using names 
[(NOJPAGE 
CPAGE 
[NOJDEBUG_SYMBOLS 
LOAD 
EXTERN 


C 4. Commands that are position-independent in the command file are 
processed next, but they are operated on in the following order: 


1. COMMON, SECT, PUBLIC 

2. MERGE 

3. ALIAS 

4. ORDER, SORDER 

5. ABSOLUTE, INDEX, INITDATA 


6. Commands that end command processing are processed last: 


END 
; EXIT 


C 
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Linker Commands 


The linker commands in this chapter are organized alphabetically. An alphabetical 
listing of the linker commands is shown in Table 11-1. 
Table 11-1. Alphabetical Listing of the Linker Commands 


Command Function 


| ABSOLUTE _ Specifies Sections to Include in Absolute File 
ALIAS Specifies Section Assumed Name 
ALIGN Sets Alignment for Named Section 
ALIGNMOD Sets Alignment for Module Sections 
BASE Specifies Location at Which to Begin Loading 
, CASE Controls Case-Sensitivity 
CHIP Specifies Target Microprocessor 
Comment (* and ;) Specifies Linker Comment 
COMMON Sets Common Section Load Address 
CPAGE Sets Common Section to be Page Relocatable 
DEBUG_SYMBOLS Retains or Discards Internal Symbols 
END Ends Command Stream and Finishes Linking 
ERROR Modifies Message Severity 
EXIT Exits Linker Without Linking 
EXTERN Creates External References 
FORMAT Selects Output Format 
INCLUDE Includes a Command File 
INDEX : Specifies Run-Time Value of Register An 
INITDATA Specifies Initialized Data in ROM 
LISTABS Lists Symbols to Output Object Module 
LISTMAP Specifies Layout and Content of the Map 
LOAD Loads Specified Object Modules 
LOWERCASE Shifts Names to Lowercase 
MERGE Combines Named Module Sections 
NAME Specifies Output Module Name 
ORDER Specifies Long Section Order 
PAGE Sets Page Alignment 
PUBLIC Specifies PUBLIC Symbols (External Definitions) 
RESADD Reserves Region of Memory 
RESMEM Reserves Region of Memory 
SECT Sets Noncommon Section Load Address 
SECTSIZE Sets Minimum Section Size 
SORDER Specifies Short Section Order 
START Specifies Output Module Starting Address 
UPPERCASE Shifts Names to Uppercase 
WARN Modifies Message Severity 
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Table 13-1. Alphabetical Listing of the Linker Commands (cont) 


Command Function 


SORDER Specifies Short Section Order 
START Specifies Output Module Starting Address 
UPPERCASE Shifts Names to Uppercase 
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Syntax 
ABSOLUTE Sname(,sname)... 
Description 


sname Names relocatable section to be placed into the absolute 
output object module. 


The ABSOLUTE command lets you specify that only the code and data from 
certain, specified program sections be included in the absolute output file. Without 
the ABSOLUTE command, code and data from all sections in the input modules 
are placed into the absolute output file. 


The ABSOLUTE command allows implementation of code overlays. Typically, in 
an application employing overlays, there is a main code section and several overlay 
sections. Usually, the main section is always resident in memory. The overlays are 
not resident, but are loaded into memory as needed during program execution. 
However, the code in the overlay sections needs to be linked to locations in the main 
section and vice versa. 


When using the ABSOLUTE command, only code and data from relocatable 
sections are put into the output. Code and data from absolute sections (i.e., specified 
using ORG) are never put into the output when the ABSOLUTE command is used. 


Example 


The following example shows how to link an application consisting of a main 
Program and two overlays. It requires three load operations and three linker 
command files. 


All the code and data for the main section is in section MAINSECT. All the code for 
the first overlay is in section ovisecr, and all the code for the second overlay is in 
section OV2SECT. 
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Linker command file for main section: 


Linker commands for first overlay section: 


SECT MAINSECT=§$1000 
SECT OV1SECT=$2000 
SECT OV2SECT=$2000 


ABSOLUTE MAINSECT 


LOAD MOD1,MOD2, ...,MODn 


END 


SECT MAINSECT=$1000 
SECT OVISECT=$2000 
SECT OV2SECT=$2000 


ABSOLUTE OV1SECT 
LOAD MOD1,MOD2,...,MODn 


END 


a 


Linker commands for second overlay section: 
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SECT MAINSECT=$1000 
SECT OVISECT=$2000 
SECT OV2SECT=$2000 


ABSOLUTE OV2SECT 
LOAD MOD1,MOD2,...,MODn 


END 


3 
? 


3 


ABSOLUTE 


Locate the main section. 
Locate first overlay. : 
Second overlay will cause 
ERROR: Section Overlap. 
Only this section goes 
into the output file. 
Load all modules for main, 
overlay 1, and overlay 2. 


Locate the main section. 
Locate first overlay. 
Second overlay will cause 
ERROR: Section Overlap. 
Only this section goes 
into the output file. 
Load all modules for main, 
overlay 1, and overlay 2. 


Locate the main section. 

Locate first overlay. 

Second overlay will cause 

ERROR: Section Overlap. 

Only this section goes 
into output file. 

Load all modules for main, 
overlay 1, and overlay 2. 
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| ALIAS — Specifies Section Assumed Name Y 
Syntax 


ALIAS Glias_sname, sname 


Description 
alias_sname Specifies assumed section name. 
sname Specifies section name. 


The ALIAS command lets you specify that sname be considered the same as 
alias_sname. The linker will load parts of alias_sname sections contiguously as if 
they were parts of the same same section. The resulting output object file will 
show the two combined sections under the name alias_sname. Without the ALIAS 
command, the linker would load the parts of those two sections in separate areas. 


The ALIAS command is similar to the MERGE command in that it can combine 

differently named sections. However, the ALIAS command can combine only two 

sections, and the subsections of the two sections are combined in the order in which 

they are encountered with the LOAD command. MERGE command arguments on 

the other hand are combined in the order specified. It is an error to use ALIAS and ie 
MERGE during the same link session. J 


Note 


MERGE and ALIAS are mutually exclusive. Any attempt to 
use both commands in the same session will result in an error. 


Example 


The following command file shows the ALIAS command. 


ALIAS sectl sect3 
FORMAT IEEE 


LOAD alias 
END 


OUTPUT MODULE NAME: alias 
OUTPUT MODULE FORMAT: IEEE 
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ALIAS 
The resulting link map shows that sect 3 is considered the same as sect. 
SECTION SUMMARY 
SECTION ATTRIBUTE START END LENGTH ALIGN 
sectl NORMAL CODE 00000000 00000007 00000008 2 (WORD) 
sect2 NORMAL CODE 00000008 o000000B 00000004 2 (woRD) 
sect4 NORMAL CODE oooo000C)§=—ON0DDDOF §=—00000004 =2: (woRD) 
sect3 (sect1) 00000000 00000007 00000008 2 (WORD) 
MODULE SUMMARY 
MODULE SECTION: START SECTION: END FILE 
alias sect1:00000000 sect1:00000003 alias.o 
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sect2:00000008 
sect1:00000004 
sect4:0000000C 


sect2:0000000B 
sect1:00000007 
sect4: 0000000F 
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ALIGN — Sets Alignment for Named Section 


Syntax 
ALIGN sname-=align_ value 
Description 
sname Specifies section name. 


align value Specifies a constant which is a power of 2 between 1 and 22. 


Every relocatable module section has an alignment attribute. When the module 
section is located, its base address is made a multiple of the alignment by the linker. 


The ALIGN command sets the alignment of the beginning of the combined section 
only. If any of the module subsections that make up the combined section has an 
alignment that exceeds the setting, a warning will be generated and the combined 
section will have the greater alignment. 


Example 


If modulea.src has the following: 
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opt case 
sect sectl 
dcb.b 1,3 
sect sect2,4 
dcb.b 1,4 
sect sect3,1 
nop 
decb.b 1,5 
end 

and moduleb.src has the following: 
opt case 
sect sectl 
decb.b 1,3 
sect sect2,1 
dcb.b 1,4 
sect sect3,4 
nop 
dcb.b 1,5 
end 
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ALIGN 


the map of the alignment will be: 


ALIGN sect1,512 


ALIGNMOD sect1,;16 


; align sectl combined section on 
7 512 byte boundaries 


} align sectl module sections on 


7 16 byt 
ALIGNMOD sect2,8 ; 

7 8 byte 
ORDER sect3, sect2,sectl 
* 
LOAD modulea,moduleb 
END : 
SECTION SUMMARY 
SECTION ATTRIBUTE START 
sect3 NORMAL CODE 00000000 
sect2 NORMAL ROM 00000008 
sectl NORMAL DATA 00000200 
MODULE SUMMARY 
MODULE SECTION: START SE: 
modulea sect1:00000200 


sect2:00000008 
sect3:00000000 
moduleb sect1:00000210 
sect2:00000010 
sect3:00000004 
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boundaries 


END 
00000006 


00000010 
00000210 


CTION ; END 


align sect2 module sections on 


LENGTH 
00000007 


00000009 
00000011 


FILE 


ALIGN 


4 (LONG) 
8 
512 


sect1:00000200 modulea.o 


sect2:00000008 
sect3:00000002 
sect1:00000210 
sect2:00000010 
zzeot3: 00000006 


moduleb.o 
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ALIGNMOD — Sets Alignment for Module Sections 7) 
Syntax 


ALIGNMOD sname=align_value 


Description 
sname Specifies section name. 
align_value Specifies a constant which is a power of 2 between 1 and 277. 


Every relocatable module section has an alignment attribute. When the module 
section is located, its base address is made a multiple of the alignment by the linker. 


The ALIGNMOD command may be used to increase the alignment attribute of the 
module sections of the named module. Note that the alignment of a given combined 
section is the largest of its inclusive module sections. 


O 
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BASE — Specifies Location at Which to Begin Loading 


Syntax 


BASE mumber 


Description 


number Specifies an absolute number. 


The BASE command specifies the base address of the output object module. The 
base address is the lowest address at which the first section in a module is placed, 
provided that this section does not have its load address specified in a SECT or 
COMMON command. 


Example 


The following command file does not have a BASE command. 


LOAD base 
END 


The resulting link map shows the default base address of the first section is 0. 
SECTION SUMMARY 


SECTION ATTRIBUTE START END LENGTB ’ ALIGN 
sectl’ NORMAL CODE 00000000 00000003 00000004 2 (WORD) 
sect2 NORMAL CODE 00000004 00000007 00000004 2 (woRD) 
sect3 NORMAL CODE 00000008 00000008 00000004 2 (WORD) 
2 (WORD) 


sect4 NORMAL CODE 0000000C 0000000F 00000004 


The following command file does have a BASE command. 


BASE $1400 
LOAD base 
END 


The resulting link map shows the base address of the first section is 1400 
hexadecimal. 
SECTION SUMMARY 


SECTION ATTRIBUTE START END LENGTH ALIGN 
sectl NORMAL CODE 00001400 00001403 00000004 2 (woRD) 
sect2 NORMAL CODE 00001404 00001407 00000004 2 (WORD) 
sect3 NORMAL CODE 00001408 00001408 00000004 2 (woRD) 
2 (WORD) 


sect4 NORMAL CODE 0000140C 0000140F 00000004 
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CASE — Controls Case-Sensitivity 
Syntax 


[NO]CASE [class{,class]...] 


Description 
class Specifies one of the following class names: 
PUBLICS All public and external names. 
MODULES All section names. 
SECTIONS All module names. 


The CASE command controls the case-sensitivity of various classes of symbolic 
names by specifying that upper- and lower-case characters are distinct in name 
comparisons. Symbolic names in the indicated class(es) are not modified on input. 


NOCASE forces upper-case names. 


If class is not specified, all classes of names are affected. Each ciass can have only 

one case specification (ie, CASE, UPPERCASE, or LOWERCASE). CASE, 
LOWERCASE, and UPPERCASE take immediate effect and should be used 
early in the command file. 


Related commands include LOWERCASE and UPPERCASE. 
Example 


Given the following command file: . 


CASE PUBLICS 

LISTMAP PUBLICS 

LOAD modulea, moduleb, modulec 
END 


All public and external names will be unchanged in the linker’s output file. The 
generated link map will contain a PUBLIC SYMBOL TABLE section that will show all 
the public and external names. For example: 


SYMBOL SECTION ADDRESS MODULE 
G1 sect3 00001200 MODULEA 
g2 sect3 00001204 MODULEB 


‘63 sect3 00001208 MODULEC 
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ae CHIP — Specifies Target Microprocessor 


Syntax 


CHIP target{, 7) 


Description 
target Specifies the type of chip. This expression evaluates to 
68000, 68008, 68010, 68020, 68030, 68040, 68851, or 
CPU32. 
(default: 68000) 
n Overrides the default target bus width. The maximum 


address is 2"-1. The high short-addressable area address 
range is from (2”-$8000) to (2”-1). 
(default: maximum width for the target microprocessor) 


The CHIP command stipulates on which microprocessor the linked code is to run. 
This command affects the section alignment attribute (see Section Alignment 
Anribute in Chapter 5, Relocation, in this manual). 


The chief differences among the microprocessors in the 68000 family pertain to the 

x size of the address space and to the addresses of the high memory area which can 
be accessed with the absolute short addressing mode. The linker places sections 
with the short attribute in this area of memory (or in the low short-addressable area 
of memory, which is from 0 to $7FFF for all targets). 


- Ifa CHIP command is not present, the target microprocessor type defaults to the 
largest model used in the modules. For example, if three modules assembled on the 
68000, the 68010, and the 68020 are ready to be linked and no CHIP command is 
indicated before the LOAD command, the target microprocessor will be 68020. 


The differences in memory addressing among the 68000 family chips are 
summarized in Table 11-2. 
Table 11-2. 68000 Family Memory Addressing 
CHIP Maximum Address High Short Addressable Area 
of Memory 


$FF8000 to $FFFFFF 
$F8000 to $FFFFF 


$FF8000 to $FFFFFF 

$FFFF8000 to $FFFFFFFF 
$FFFF8000 to $FFFFFFFF 
$FFFF8000 to $FFFFFFFF 
$FFFF8000 to $FFFFFFFF 
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All absolute addresses which appear in later commands or object modules are 


checked against the bounds established by the CHIP command. 


Overriding the maximum address bus width implied for the target microprocessor 
lets the maximum address in memory be limited regardless of the maximum address 


bus width possible for the chip. 


Example 


FORMAT S 
CHIP 68020,24 


For S-Record output, the target address bus width argument sets the S-Record type. 
By default, CHIP 68020 causes S3 records to be produced. However, if the bus 
width is 24 or less, S2 records are produced. If the address bus width is greater than 


24, S3 records are produced. 


Example 


© This is the linker command file with 

® the default bus width picked for the 68020. 
x 

CHIP 68020 

FORMAT S 

LOAD test 

END 


* This is the absolute file, $3 records 
* are produced by default. 

® 

$006000048445218 

$306000000006495 

$5030001FB 

S70500000000FA 


This is the linker command file with 
the bus width, 20, explicitly indicating 
that S2 records are desired. 


CHIP 68020,20 
LOAD test 
END 


® This is the absolute file. S2 records are 

* produced because the bus width qualifier is 20. 
* 

$00600004844521B 

$2050000006496 

$5030001FB 

$804000000FB 
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( a Comment — Specifies Linker Comment 


Syntax 


* 
or 


Description 


Comments document linker command sequences. If an asterisk (*) is used to 
indicate the start of a comment, it must be located in column 1 or preceded by 
blanks or tabs. If a semicolon (;) is used, it can occur anywhere on the line. 


Comments are allowed anywhere in the command file. They are even allowed on 
the same line as other commands. 


Example 


* Linker example. 
® 


* 


LOAD modl.obj ; This is the only module loaded. 
END 
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COMMON — Sets Common Section Load Address 


Syntax 


COMMON sname [= | ,] value 


Description 
sname Specifies the section name. 
value Specifies the load address of the common section. 


The COMMON command specifies the load address of a common section. If 
COMMON is used, it must be specified before any LOAD command. 


Enter the section name followed by the address at which to begin loading the 
section. The address specified is rounded up to the next higher word boundary in all 
cases and, if paging is specified for this common section, to the next higher page 
boundary. 

If this is the first occurrence of this section name, it is given the attributes of 
common and Jong. 


Multiple COMMON commands with the same section name are accepted without { } 
a waming, but only the last one is used. 


The value is separated from the section name by a blank, comma, or equal sign. 
Example 


The following command file sets the load address of the common section sect1 at 
2000 hexadecimal. 


COMMON sectl = $2000 ; Locate the common section sectl at 2000 hex 


LOAD commonl, common2 
END 


The resulting link map shows that the common section sect1 was loaded for 
common and commonz at 2000 hexadecimal. 


CUTPUT MODULE NAME: common 
OUTPUT MODULE FORMAT: IEEE 


VO 
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e SECTION SUMMARY 


SECTION ATTRIBUTE START END LENGTH ALIGN 
sectl COMMON 00002000 000020FF 00000100 2 (WORD) 
sect2 NORMAL CODE 00000000 00000007 00000008 2 (WORD) 


MODULE SECTION: START SECTION: END FILE 

commonl sect1:00002000 sect1:0000205F commonl.o 
sect2:00000000 sect2:00000003 

common2 sect1:00002000 sect1:000020FF common2.o 
sect2:00000004 sect2:00000007 
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Linker Commands 


CPAGE — Sets Common Section to be Page Relocatable 


* 11-20 


Syntax 


CPAGE snmame 


Description 


sname Specifies a section name. 


The CPAGE command modifies the relocation type of common section(s) in the 
input object modules to page. It lets you override the default relocation type of word 
for a common section. The PAGE command, on the other hand, sets the relocation 
type of a noncommon section to page. 


Since all subsections of a common section are loaded at the same address, the 
CPAGE command need only be used once per section at the beginning of the 
loading process. Once page relocation is turned on for a common section, it cannot 
be turned off for later subsections of the section. 


If sname is the first occurrence of the section name, it is assigned the attributes 
common and long. 


Example 


In the following command file, the starting address of sect1 is page-aligned to 
2100 hexadecimal. 


COMMON sectl = $2020 ; Locate the common section sectl at 2020 hex 
CPAGE sectl ; aligns the common section sectl at 2100 hex 


* sectl in commonl.o has a size of $60 
* sectl in common2.o has a size of $100 


* non-common section sect2 has a size of 4 in both modules 


LOAD commoni, common2 
END 
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~) 


OUTPUT MODULE NAME: cpage 
OUTPUT MODULE FORMAT: IEEE 


SECTION SUMMARY 


SECTION ATTRIBUTE START 
sectl COMMON 00002100 
sect2 NORMAL CODE 00000000 


MODULE SECTION: START 
commonl sect1:00002100 
sect2;:00000000 
common2 sectl:00002100 
( ‘ sect2:00000004 
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END LENGTH 


CPAGE 


The resulting link map shows that the load address for sect1 is 2100 hexadecimal. 


ALIGN 


O0002iFF 00000100 2 (WORD) 
00000007 00000008 2 (WORD) 


SECTION: END 


sect1:0000215F 
sect2:00000003 
sect1:000021FF 
sect2:00000007 


FILE 


commonl.o 


common2.o 
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DEBUG_SYMBOLS — Retains or Discards Internal Symbols 


41-22 


Syntax 


{NO] DEBUG_SYMBOLS 


Description 


The DEBUG_SYMBOLS command provides module-by-module control of 
internal (local) symbols. 


The DEBUG_SYMBOLS command includes internal symbols in the map file as 
well as in the output object module; NODEBUG_SYMBOLS suppresses them. 


The DEBUG _SYMBOLS and NODEBUG_SYMBOLS commands can appear 
anywhere in a linker command file. The command remains in effect until it is 
overridden by its complementary command or until the end of the command file. 


The DEBUG_SYMBOLS command works in conjunction with the LISTMAP 
and LISTABS commands. If LISTMAP NOINTERNALS has been specified, the 
DEBUG_SYMBOLS command will have no effect on the map file. Similarly, if 
LISTABS NOINTERNALS has been specified, the DEBUG_SYMBOLS com- 
mand will have no effect on the absolute file. For DEBUG_SYMBOLS to take 
effect, INTERNALS must be tumed on by either the LISTABS or LISTMAP 
command. 


Note 


[NO]DEBUG_SYMBOLS was formerly known as [NJLIST P. 
The {NJLIST P command is no longer supported. 
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he END — Ends Command Stream and Finishes Linking 


Syntax 
END 
Description 


The END command starts the final steps in the load process. After an END 
command is found, the linker completes the load, produces an output object 
module, and returns you to the host computer operating system. 


Example 


The following command file specifies that modulea.obj, moduleb.obj, and 
modulec.obj be loaded. After these modules have been loaded, the linker produces 
an output object module and retums you to the host operating system. 


® Load first two modules 
LOAD modulea.obj,moduleb.obj 
*® Load last module 

LOAD modulec.obj 

END 


& 
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ERROR — Modifies Message Severity Y 
Syntax 
(NO] ERROR iiabes, Manion seth 
Description 
number Specifies a message number. 


The ERROR and NOERROR commands specify that the message number 
indicated by number is to be treated as an error or a nonerror. 


These commands have a global effect from the point at which the linker processes 
the information contained in the command. A subsequent ERROR or NOERROR 
command overrides any values set by a previous one. 


Fatal errors and the errors or wamings that are generated as a result of a 
syntactically or semantically incorrect ERROR or NOERROR command cannot 
be overriden. 


Examples 


ERROR 349 ) 
Upgrades warming 349 to an error condition. af 


NOERROR 324 . 
Turns off error condition 324. — 
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et EXIT — Exits Linker Without Linking 
Syntax 
EXIT 


Description 


The EXIT command can be the last command in the command stream. This 
command prevents the final Joad from taking place but reads all object modules and 
commands, checking for errors. EXIT stops linker execution and does not generate 
an output object module. ; 


(~ 
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EXTERN — Creates External References 


Syntax 


EXTERN M@meée[,name]... 


Description 


name Creates an external reference symbol name. 


The EXTERN command creates external references for the linker to resolve. You 
can create these extemal references by using the EXTERN command to add an 
entry to the linker’s internal symbol table for each named symbol. Information 
indicating that these are external symbols to be resolved is inserted into the symbol 
table, If the symbol already exists in the symbol table either as an external reference 
or definition, the EXTERN command is ignored and a warming is issued. 


The EXTERN command can appear anywhere in a command file. Multiple 
EXTERN commands can appear in a command file. 


The EXTERN command is in effect for a given name when that name is specified 
in the command. It remains in effect until the end of the command file, but it has no 
effect before the point of specification. An EXTERN command with a specific 
name must appear before the LOAD command for the library in which the specific 
external symbol is defined in order to force the loading of the module associated 
with the external symbol. 


The -u name linker command line option (for non-VMS hosts) or the 
/REFERENCE= name option (for VMS host) has the same effect as if an 
EXTERN command is inserted into the command file before the first LOAD 
command, if any. 


Example 


11-26 


EXTERN gl 
LOAD modulel.o,module2.o,textern.lib 
END 


In this example, the symbol g1 is not defined in both module1 and module2. So if 


a definition of g1 exists in textern.1ib, the appropriate module that contains the 
definition will be force-loaded in order to resolve the external reference. 
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FORMAT — Selects Output Format 


Syntax 
FORMAT type 
Description 
type Specifies output format generated by the linker. Valid values are: 
HP HP 64000 Object Module Format (HP-OMF). 
IEEE Microtec Research extended IEEE-695 format. 
(default) 
s Motorola S-Record file format. 
NOABS Prevents an absolute file from being produced. 
INCREMENTAL 


Specifies that incremental linking is to be 
performed. Output files are created in Microtec 
Research extended IEEE-695 format. 


The FORMAT command lets you specify the output object module format. If an 
unsupported type specifier is encountered, an error or waming will be generated and 
the default output format will be produced. 


The FORMAT command has a global effect. If multiple FORMAT commands are 
encountered, a warming message will be generated and the format specified by the 
first FORMAT command will be used. If no FORMAT command is specified, the 
output will be produced in IEEE-695 format which is the default format for 
incremental linking. 


If noags is specified, no object file will be produced; however, internal processing 
will be carried out and a map file will be produced if requested. As with the other 
format type, NoABS cannot be used in conjunction with any other type. If this 
conditions occurs, an error or waming will be issued and the FORMAT command 
will be ignored. 


Note 


FORMAT NOABS was formerly known as NLIST O, and Format 
INCREMENTAL «vas formerly known as LIST R. 
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INCLUDE — Includes a Command File YS) 
Syntax 
INCLUDE filename 
Description 
filename Specifies a file to be included in the linker command file. 


The INCLUDE command lets additional command files be included in a linker 
command file. At the point the INCLUDE command is specified, the text contained 
in the file specified by filename is included in the linker command file. 


The INCLUDE command can appear multiple times anywhere in a linker 
command file and can be nested up to a maximum depth of 16 (8 for DOS hosts). 


Example 

If setup.opt contains: 
CHIP 68010 | 
BASE $500 ; | 

ae 

and a command file contains the following INCLUDE command: ) 
INCLUDE setup.opt 
LOAD modulel,module2 

the resulting link map will be: 


INCLUDE setup.opt 

CHIP 68010 

BASE $500 

*** End of include file: /some/where/setup.opt 
LOAD modulel,module2 


An extra comment line: 
*** End of include file: /some/where/setup.opt 


with the absolute path name of the included file (UNIX path name in this example) 
was added for readability. 


U 
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INDEX — Specifies Run-Time Value of Register ‘‘An’’ 


Syntax 


INDEX ?REGn, sectname [ , offset) 


Description 


REGn Specifies an address register: A2, A3, A4, or AS. 
sectname Specifies a relocatable section whose load address plus offset 
is equal to the run-time value of address register REGn. 
offset Specifies a number to be added to the load address of the 
Telocatable section specified. The result is the run-time value 
of REGn. 


The INDEX command informs the linker of the run-time value of an address 
register An, (where n = 2, 3, 4, or 5). The value you associate with a particular An 
register will equal a relocatable section's load address plus an offset value. 


A public symbol equal to the run-time value specified will be created in the form 
?An. With the XREF directive, you can declare this public symbol to be an external 
symbol in the assembly language source file. You can use this symbol to initialize 
the appropriate address register. 


The linker must know the run-time value of an address register whenever you use 
assembly language operands which combine relocatable expressions and address 
register indirection. For example, consider the following assembler syntax: 


<relocatable_expression> (an) ot (<relocatable_expression>, An) 


Operands with the syntax shown above will generate the Address Register Indirect 
with 16-bit displacement addressing mode. The relocatable expression in the syntax 
above is an effective address (i.e., the location to be accessed). For more 
information on the notation used to show this syntax, see any Motorola User's 
Manual. 


The linker calculates the 16-bit displacement using the equations: 


<effective_address> = An + disp 
displacement = <effective_address> - An 
displacement = <relocatable_expression> - An 


The INDEX command makes An a known value which lets the linker calculate the 
displacement. If you do not use the INDEX command, the linker will calculate the 
displacement under the assumption that the run-time value of the address register is 
Zero. 
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Other addressing modes which can contain relocatable expressions in conjunction oe) 
with address register indirection are: Address Register Indirect: with Base 
Displacement and Index, Memory Indirect Post-Indexed, and Memory Indirect Pre- 
Indexed. 
Example 
INDEX ?A2,DATA1, 80008 This offset allows "{A2)" indirect 
addressing to access a full 64K 


bytes in section DATA1 (using a 
16-bit signed displacement). 


Ne Ne te te 


See Chapter 4, Addressing Modes, for more information on how the INDEX 
command can be used with array addressing for registers A2 through A5. 
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INITDATA — Specifies Initialized Data in ROM 
Syntax 


INITDATA [sectname (,Sectname}]...] 


Description 


sectname Specifies a section name. 


The INITDATA command initializes data variables in RAM before a program is 
executed. This feature is intended for use with data which has an initialized value 
and thus needs to be stored in ROM. For these applications, it is often necessary to 
copy the initialized values for all variables from the ROM section to a RAM section 
where the variables will reside and be modified during execution time. 


The INITDATA command causes the linker to automatically create a new data 
section ?7INITDATA, and to fill the section with a copy of all the initialized data 
values contained in the sections named in the command string. If a section type is 
specified, then all sections of the specified type are copied into the ?7INITDATA 
section. The INITDATA command is legal only during a final link. 


A separate initialization routine, initcopy( ), should be called at the beginning of 
runtime to invoke the copy function and hence to reinitialize data variables each 
time the program runs. This routine checks that the special bytes generated by the 
linker in the section ?7INITDATA provide the necessary information such as the 
copy destination address, copy size and the mark for the end of the section content. 
The initcopy( ) routine is provided in the run-time library with the compiler 
distribution files. 


The ROM section ??7INITDATA may be ordered and assigned an address using 
standard linker commands. The user cannot create ??INITDATA either from the 


’ assembler or compiler (unless it is an empty section representing a reference to the 


section, i.e., the STARTOF. or .SIZEOF. operator was used). 


Exampies 


INITDATA vars, strings 


The following linker command file locates section data at $8000 while specifying 
its ROM address as $2000. 


SECT prog=$1000 + Locate program in ROM. 
SECT data=$8000 # Locate data in RAM. 
INITDATA data * Data’s ROM address in ROM. 
LOAD initest 

END 


f 
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LISTABS — Lists Symbols to Output Object Module 


Syntax 

LISTABS option[, option)... 
Description 

option One of the following: 


[NO] INTERNALS Places the local symbols in the output 
object module and omits any symbols 
that are defined in modules for which the 
NODEBUG_SYMBOLS comman¢ is in 
effect. 

(default: INTERNALS) 


[NO] PUBLICS Places globally-defined symbols into the 
output object module. 
(default: NOPUBLICS) 


The LISTABS command controls the output of certain items to the output object 
module. Multiple LISTABS commands can be specified and have a cumulative 
effect. However, since LISTABS command options have a global effect, options 
that are inconsistent with a previous LISTABS command cannot be specified in a 
succeeding LISTABS command (e.g., LISTABS PUBLICS can be followed by 
LISTABS INTERNALS , PUBLICS, but not by LISTABS NOPUBLICS.) If such a condition 
occurs, a watning message will be issued at this and at each subsequent point of 
conflict, and the first specification will be used. 


Note 


LISTABS PUBLICS was formerly known as LIST D, and 
LISTABS INTERNALS was formerly known as LIST S. The LIST 
command is no longer supported. 
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( : LISTMAP — Specifies Layout and Content of the Map 


Syntax 


LISTMAP option(, option]... 


Description 
option One of the following: 
[NO]CROSSREF Causes a cross-reference listing to be 
output to the map file. 
(default: tocROSSREF) 
[NO] INTERNALS [/BY_NAME | /NAME] 
Causes a listing of the non-public (local) 
symbol table to be output to the map file. 
The use of INTERNALS can severely 
increase link time. 
If /BY_NAME Of /NAME is specified, the 
symbol table is listed in alphabetical 
order. 
oO (default: NoINTERNALS) 


[NO]PUBLICS [/BY_ADDR | /ADDR | /BY_NAME { /NAME] 
Causes a listing of the public symbol ta- 
ble to be output to the map file. If 
/BY_NAME or /NAME is specified, the pub- 
lic symbol table is listed in alphabetical 
order. If /BY_ADDR of /ADDR is specified, 
the public symbol table is listed in ad- 
dress order. 

' (default: NopuBLiIcs) 


LENGTH lval Specifies that the map file page length is 
set to Ival lines where lval is a numeric 
value between 5 and 255. The default 
value is 55 lines including any header 
information generated by the linker. 
(default: LENGTH 55) 


The LISTMAP command controls the output of certain items to the linker’s map 
file. The LESTMAP command options have a global effect. Multiple LISTMAP 
commands that do not have any inconsistencies with previous LISTMAP 
commands can be specified and have a cumulative effect. 


Co 
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If multiple LISTMAP PUBLICS commands appear, the last specification takes YY) 
effect. 


Note 


LISTMAP CROSSREF was formerly known as LIST C. trstmap 


INTERNALS was formerly known as LIST T, and tistmap 
PUBLICS was formerly known as LIST X. The LIST command 
is no longer supported. 


O 
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Linker Commands LOAD 


LOAD — Loads Object Modules 


Syntax 


LOAD [-]rmodule [, {-]module]... 


Description 


module Specifies the name and path of a file in which the object 
module or library resides, The minus sign (-) in front of the 
module name forces the linker to load all modules contained 
in the named file. 


The LOAD command specifies one or more input object modules to be loaded. 
Input object modules can consist of relocatable modules from the assembly process, 
Telocatable modules from incremental linking, or libraries. The input file(s) 
specified, whether they contain relocatable object modules (output of the 
assembler) or libraries (output of the librarian), are differentiated on the basis of 
their internal format and are handled identically by the linker. 


Backward external references within a library are resolved correctly. However, 
external references to a library from a subsequently-loaded file are generally not 
resolved correctly. For this reason, libraries should be loaded after all non-libraries. 
The linker will load only those library modules which are necessary to resolve 
undefined external references (XREFs). If two libraries makes external references 
to the other, it is generally necessary to LOAD one of them twice (for example, 
LOAD LIBA, LIBB, LIBA) to pick up all the necessary modules. 


Incremental linking accepts relocatable modules produced from the assembly and 
produces a single relocatable object module. See Incremental Linking in Chapter 
10, Linker Operation, for more information. 


Object modules can be read from a combination of files and are loaded in the order 
specified with each subsection within each module being loaded into memory at a 
higher address than all preceding subsections within its section. You can use as 
many LOAD commands as needed. 


The linker searches for module in the following locations and order: 


Absolute path if specified. 

Relative path. 

Using PATH environment variable. 

Using MRI_68K_LEB environment variable. 


Appr 
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Example 


” LOAD command example 
BASE $4000 

LOAD filel, file2 

LOAD mathlib 

END 


UO 
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LOAD_SYMBOLS — Loads Object Modules 


with Symbol Information 


Syntax 


LOAD SYMBOLS [-]module [,[{-]module]... 


Description 


module Specifies the name and path of a file in which the object 
module or library resides. The minus sign (-) in front of the 
module name forces the linker to load all modules contained 
in the named file. 


The LOAD SYMBOLS command allocates space for modules in the specified 
object modules and also retains all PUBLIC symbol definitions. Code and data for 
the specified modules are omitted from the output file; only symbol table and oe 
information is written to the absolute file. 


Input object modules can consist of relocatable modules from the assembly process, 
relocatable modules from incremental linking, or libraries. The input file(s) 
specified, whether they contain relocatable object modules (output of the 
assembler) or libraries (output of the librarian), are differentiated on the basis of 
their internal format and are handled identically by the linker. 


Incremental linking accepts relocatable modules produced from the assembly and 
produces a single relocatable object module. See Incremental Linking in Chapter 


‘10, Linker Operation, for more information. 


The linker searches for module in the following locations and order: 
Absolute path if specified. 
Relative path. 


Using PATH environment variable. 
Using MRI_68K_LIB environment variable. 


x YN 


If module is a library, LOAD_SYMBOLS retains all external symbols in each 
loaded module so that forward references within the library cause allocation of 
space for subsequent modules. If module is not a library, all external symbols are 
ignored. 


Example 


LOAD_SYMBOLS modl, mod2 
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LOWERCASE — Controls Case-Sensitivity oe | 
Syntax | 


LOWERCASE [class[,class]...) 


Description 
class Specifies one of the following class names: 
PUBLICS All public and external names. 
MODULES All section names. 
SECTIONS All module names. 


The LOWERCASE command causes the linker to shift names to lowercase on 
input. All symbolic names of the specified class(es) will appear in lowercase in the 
linker’s output files. 


If class is not specified, all classes of names are affected. Each class can have only 
one case specification (i.e, CASE, UPPERCASE, or LOWERCASE). CASE, 
LOWERCASE, and UPPERCASE take immediate effect and should be used | 
early in the command file. 


Example ( ) 
Given the following command file: : : 


LOWERCASE PUBLICS 
LISTMAP PUBLICS ' 
LOAD modulea, moduleb, modulec 

END 


All public and external names will be set to lowercase in the linker’s output file. The 
generated link map wili contain a PUBLIC SYMBOL TABLE section that will show all 
the lower-case public and external names. 


For example: | 
. + . i} 

PUBLIC SYMBOL, TABLE 1 
SYMBOL SECTION ADDRESS MODULE | 

gl sect3 00001200 MODULEA 

92 sect3 00001204 MODULEB | 


g3 sect3 00001208 MODULEC 


() 
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Linker Commands MERGE 


MERGE — Combines Named Module Sections 
Syntax 


MERGE merge_name merge_arg|,merge_arg}... 


Description 
merge_name Specifies the name of the new, combined section. 
merge_arg : One of the following: 
sectname Section name. 
{sectname, module} 


Section name followed by a module 
name. The braces are required. 
Both sectname and module can be replaced by the wild card 
character © to indicate all sections or all modules 


The MERGE command merges all the named subsections into a new section. The 
default linker behavior merges sections with the same name into a like-named 
section. This command lets you concatenate arbitrary lists of subsections. The new 
section can then be placed anywhere in memory using standard linker commands. 
If the section merge_name already exists and it is not specified in the merge_arg(s), 
the sections specified in merge_arg(s) will be placed before merge_name and the 
final combined sections will use the name merge_name. Multiple MERGE 
commands with the same merge_name are concatenated. 


MERGE can be used during both incremental and absolute links. 


MERGE commands will be executed in the order that they are found in the 
command file. See Command Position Dependencies at the beginning of this 
chapter for a description of the order in which commands are executed relative to 
other commands, 


Note 


MERGE and ALIAS are mutually exclusive. Any attempt to 
use both commands in the same session will result in an error. 
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Example Y 


* There are three modules each containing three 
* sections: SECT1, SECT2, SECT3. 

» 

MERGE NEW_SECT SECT1, {SECT2,MOD1}, {SECT3,MOD3} 
MERGE NEW_SECT {SECT3,MOD2} 

» 

SECT NEW_SECT=$1000 

SECT SECT2=$2000 

SECT SECT3=$3000 


*« 


LOAD MOD1,MOD2,MOD3 


This causes a new section with the name NEW_SECT to 

be created. It is located at $1000 

containing the following module sections in the order listed: 
SECT1/MOD1, SECT1/MOD2, SECT1/MOD3, SECT2/MOD1, SECT3/MOD3, 
SECT3/MOD2. 


There is also SECT2 located at $2000 containing: 
SECT2/MOD2, SECT2/MOD3 and 

SECT3 located at $3000 containing: 

SECT3,MOD1 


eeurv re eee ey 


O 
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NAME — Specifies Output Module Name 


Syntax 


NAME name 


Description 


name Specifies the object module name. 


The NAME command specifies the name of the final output object module. In the 
standard Motorola S-Record hexadecimal format, this appears on the first line of the 
output object file if the LISTABS PUBLICS linker command has been specified. 
Any symbol assigned values by the PUBLIC command at load time is considered 
to lie in this module which is defined at load time. 


Any legal symbol can be used for the module name. If you do not specify a name, 
the name of the output module will be specified by the rules outlined in the User's 
Guide. 


Example 


NAME READER 

FORMAT S 

LISTABS PUBLIC 
CHIP=68020 

LOAD modl.obj,mod2.obj 
END 
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Syntax 

ORDER [Sectnarne f (sect_type)] [, {Sectname | (sect_type)} }... 
Description 

sectname Specifies a section name. 


sect_type Specifies a section type enclosed in parentheses. The type 
can be one of the following: 


Code | 
Data 
Mixed 
ROM data 


vAmzoa 


The ORDER command changes the default order of assigning load addresses to 
sections (i.e., order in which the linker encountered their names). 


The ORDER commands is designed for those who do not need to specify load 

addresses for each section but who would like the sections to be placed in memory 
in a different order. If you specify load addresses for the sections, the order of the ( ) 
sections is of no particular importance. Remember, however, that even if a load 

address is specified for a certain section, any sections assigned memory space after 

that section will be loaded at the next available address. 


The ORDER command tells the linker to assign memory in the address order 
specified. The linker follows these mules for assigning memory space: 


1. All absolute sections and those’ assigned addresses explicitly are placed in 
memory first. 


2. The first section specified in the ORDER command is placed in memory at 
the first available location starting at the beginning of memory. The location 
is chosen with consideration for the alignment and size of the section. 


3. All subsequent sections specified in the ORDER command(s) are placed in 
memory at the first available location (taking in consideration alignment 
and size of the section) after the previous ORDER section. 


4. Sections named in the ORDER command with explicit addresses (rule #1) 

- ate checked to make sure that the specified order is maintained. The location 

of these sections will also set the starting point at which the linker will begin 
looking for the starting point for next section named in the command. 


Microtec Research, Inc. 


Linker Commands ORDER 
ta a PB OIE EE TE REE IT TE ELEY DSI |S 


5. If the order which the ORDER command specified cannot be maintained 
then the linker will issue a warning and continue trying to assign memory to 
the remaining sections in the ORDER command. 


6. If asection named in the ORDER command is missing a warning is issued 
and the linker will continue with the next named section, if any. 


The ORDER command applies to long sections; the SORDER command applies 
to short sections. If a section name appears in these commands for the first time it 
is assigned the appropriate length attribute, but it is assigned neither the common 
nor the noncommon attribute so that subsequently it can be either. 


If the name of a short section appears in the ORDER command, this is a fatal error. 
The final determination of which sections are short cannot be made until all 
modules have been read since any short module section declaration makes a section 
short. 


If the name of a long section appears in the SORDER command, a warning is 
printed and the section is given the short attribute. This can occur if a SECT, 
COMMON, PAGE, CPAGE, or NOPAGE command precedes the SORDER 
command, since these commands assign newly-found sections the long attribute. 


The same section name cannot appear twice in an ORDER command. Multiple 
ORDER commands are accepted without a warming. They are concatenated and 
must not contain duplicate names. 


The order of sections within each group is specified by entering section names 

separated by commas. Any sections remaining within the group are assigned 
memory space after the sections specified in the command in the order in which 
their names were encountered by the linker. 


An ORDER command can be continued to the next line by terminating it with one 
or more spaces followed by a pound sign (#). A continuation character must be 
placed like a comma between section names, 


Examples 


ORDER SEC1,COMSEG 
SORDER SEC2, SHORTSEC 


ORDER SECT1 # 
SECT2,SECT3 # 
_ SECT 


This example uses the # continuation character. 
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Syntax 


{NO]PAGE Sname 


Description 


sname Specifies a section name. 


The PAGE command modifies the relocation type of noncommon section(s) in the 
input object modules to page while the CPAGE command sets the relocation type 
of a common section to page. The NOPAGE command restores the relocation type 
of a section to word. 


The PAGE command lets you override the default relocation type (i.e., word). 
After the PAGE command is read, each subsection of the specified section loaded 
thereafter will be page relocatable until a NOPAGE command for the section is 
encountered. The NOPAGE command is legal but unnecessary unless the specified 
section has previously appeared in a PAGE command. 


The typical use of the PAGE command is to let you begin each section on a page 
boundary for ease of debugging. After debugging is completed, the page commands 
are removed to avoid wasted memory space. 


The typical use for the NOPAGE command is to turn off page relocation for 
modules which are already known to work correctly (libraries, for instance) in order 
to save memory space. 


If PAGE is in effect and this is the first occurrence of some section name, it is given 
the attributes noncommon and long. Similarly, if NOPAGE is in effect, it is given 
the long attribute, but it is assigned neither the common nor the noncommon 
attribute. 
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@ Example 


In the following command file, the page alignment is turned on, turned off, and then 


tumed on for sect1. 


SECT sectl = $32 ; Locate the beginning of sect1 at 32 hex 
PAGE sectl ; Set page alignment for sectl pushing the 
+ beginning of sectl to 100 hex 


LOAD pagel 


NOPAGE secti ; Turn off page alignment for sect 


LOAD page2 


PAGE sectl ; Reset to page alignment for sectl 


LOAD page3 
LOAD page4 
END 


The resulting link map shows the load order-dependent paging for sect.1. 


OUTPUT MODULE NAME: page 
OUTPUT MODULE FORMAT: IEEE 


-_ SECTION SUMMARY 


x Cee teetteberteteteak ted 


SECTION ATTRIBUTE START 


sectl1 NORMAL CODE 00000100 


MODULE SECTION : START 

pagel gect1:00000100 
page2 gect1:00000104 
page3 sect1:00000200 
paged sect1:00000300 


oO 
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END LENGTE 


00000303 00000204 


SECTION : END 


sect1:00000103 
sect1:00000107 
sect1:00000203 
sect1:00000303 


ALIGN 


FILE 


pagel.o 
page2.o 
page3.o 
page4.o 


2 (WORD) 
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PUBLIC — Specifies Public Symbols (External Definitions) QO 
Syntax 
pusLic symboll= {value | symbol2 [{+{-} offset)} 
Description 
symboll Assigns the name symboll to the public symbol being 
defined. 
value Assigns the constant number value to symboll!. 
symbol2 Assigns the value, relocation type, and section ID of symbol2 
to symboll. 
offset Specifies a constant number that is added or subtracted from 
symbol2, 


The PUBLIC command defines and/or changes the value of an external definition 
(XREF). The external symbols are defined at load time, which may prevent 
reassembly. This command is position independent. 


Symbol names specified by the linker’s PUBLIC command have precedence over ‘@) | 
symbol names defined during assembly. Therefore, if a symbol specified by this 
command is already an external definition from an input object module defined by 

the assembler, the value of the symbol is changed to that specified in the PUBLIC 

command. If the symbol is not already defined, it will be entered into the linker’s 

symbol table along with the specified value and will then be available to satisfy 

external references from object modules. 


Any value defined by this command is considered to be absolute (L.e., it does not lie 
in any relocatable section and will not be relocated relative to any section base). 


PUBLIC values are separated from symbols by blanks, commas, or an equal sign. 
If multiple PUBLIC commands having the same symbol are specified, the last 
value for that symbol holds and a waming message is issued. 
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Examples 


The following assembler file shows the public command. 


Command line: a68k -1 public 
Line Address 
-+; Source file to demonstrate 


2 # PUBLIC command 
3 ? 

4 OPT CASE 
5 XDEF syml, sym2 
6 

x ORG $1800 
8 00001800 4E71 syml: NOP 

9 00001802 4E71 NOP 

10 

11 60005000 sym2 EQU $5000 
12 

13 END 


The following command file shows the use of the PUBLIC command. The symbols 
sym1 and sym? have the values $100 and $200, respectively. 


LISTMAP PUBLICS 
LISTABS PUBLICS 
PUBLIC syml = $100 
LOAD public 
PUBLIC symZ2 = $200 
END 


’ As shown by the PUBLIC SYMBOL TABLE, the symbols symi and sym2 are located 


at 100 and 200 hexadecimal, respectively. 


MODULE SECTION: START SECTION: END FILE 
public 200001800 :00001803 public.o 


PUBLIC SYMBOL TABLE 


SYMBOL SECTION ADDRESS MODULE 
sya 00000100 ~=s $$ 
sym2 00000200 = $$ 
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RESADD — Reserves Regions of Memory 


Syntax 
RESADD low_dddr,high_addr 


Description 
low_addr Reserves memory starting at this address. This number is a 
numeric constant. 
high addr Reserves memory up to this address. This number is a 


numeric constant. 


The RESADD command reserves specified memory locations from low_addr to 
high_addr. The reserved memory region is made into an absolute section that will 
show up in the SECTION SUMMARY of the link map. 


If a section overlaps a reserved region, a non-fatal error message is issued. The load 
will still continue to completion, but the resulting absolute file will contain sections 
at overlapping addresses. The linker issues a warning if high _addr is Jess than 
low_addr. 


Example 
The command file: 
RESMEM $200,$100 
RESADD $2,$101 


LOAD modulel 
END 


will generate the following two entries in the sEcrron summary of the resulting link 
map if there are no overlapping sections: 


SECTION SUMMARY 


SECTION ATTRIBUTE START END LENGTH ALIGN 
ABSOLUTE 00000200 000002FF 00000100 0 (BYTE) 
ABSOLUTE 00000002 00000101 00000100 0 (BYTE) 
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( Ly RESMEM — Reserves Regions of Memory 
Syntax 


RESMEM low_addr, size 


Description 
low_addr Starting address of the memory to be reserved. This number 
is a numeric constant. 
size Specifies the number of bytes to be reserved. This number is 


a numeric constant. 


The/RESMEM command reserves specified memory locations from low_addr to 
low_addr+ (size-1). The reserved memory region is made into an absolute section 
that will show up in the SECTION SUMMARY of the link map. 


If a section overlaps a reserved region, a non-fatal error message is issued. The load 
will still continue to completion, but the resulting absolute file will contain sections 
at overlapping addresses. 


Example 
= This command file: 


RESMEM $200,$100 
RESADD $2,$101 
LOAD moduleli 

END 


will generate the following two entries in the SECTION SummaRy of the resulting link 
map if there are no overlapping sections: 


SECTION SUMMARY 


SECTION ATTRIBUTE START END LENGTH ALIGN 
ABSOLUTE 00000200 000002FF 00000100 0 (BYTE) 
ABSOLUTE 00000002 00000101 00000100 Q (BYTE) 


© 
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SECT — Sets Noncommon Section Load Address 
Syntax 


SECT sectname [{,| =<] value 


Description 
sectname Specifies the section name. 
value Specifies the load address of the section. 


The SECT command specifies the load address of a noncommon relocatable 
section. If this is the first occurrence of the section name, it is given the attributes 
noncommon and long. SECT must precede any LOAD commands. 


The section name is entered, followed by the address of the location at which to start 
loading the section. The specified address will be rounded up to the next alignment 
boundary specified either by the assembler object module or the linker ALIGN 
command in all cases and to the next page boundary if paging is in effect for the 
first subsection of the section. 


Multiple SECT commands with the same section name are accepted without a 
warning, but only the last one will be used. 


Examples 


SECT SECT1,$400 
SECT SECT2=$1320 
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& SECTSIZE — Sets Minimum Section Size 
Syntax 
SECTSIZE Snamessize (,Snamecsize}... 
Description 
sname Specifies a section name. 
size Specifies a constant representing the minimum section size, 


in bytes. 


The SECTSIZE command specifies the minimum size in bytes of a combined 
continuous memory space defined by same. It is an error to define a size less than 
the size of the combined section unless the section is type COMMON. 


If the specified section does not exist, it will be created and considered to be 
non-COMMON. 


Example 


SECTSIZE stack=$100 
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Syntax 


SORDER [Seciname | (sect_type)] [, {sectname { (Sect_type)} }... 


Description 
sectname Specifies a section name. 
sect type Specifies a section type enclosed in parentheses. The type 
can be one of the following: 

Cc Code 
D Data 
M Mixed 
R ROM data 


The SORDER command changes the default order of assigning load addresses to 
short sections (i.¢., order in which the linker encountered their names). 


The SORDER commands is designed for those who do not need to specify load 
addresses for each section but who would like the sections to be placed in memory 
in a different order. If you specify load addresses for the sections, the order of the 
sections is of no particular importance. Remember, however, that even if a load 
address is specified for a certain section, any sections assigned memory space after 
that section will be loaded at the next available address. 


The SORDER command tells the linker to assign memory in the address order 
specified. The linker follows these rules for assigning memory space: 


1. 


All absolute sections and those assigned addresses explicitly are placed in 
Memory first. 


. The first section specified in the SORDER command is placed in memory 


at the first available location starting at the beginning of memory. The 
location is chosen with consideration for the alignment and size of the 
section. 


- All subsequent sections specified in the SORDER command(s) are placed 


in memory at the first available location (taking in consideration alignment 
and size of the section) after the previous SORDER section. 


. Sections named in the SORDER command with explicit addresses (rule #1) 
_are checked to make sure that the specified order is maintained. The location 


of these sections will also set the starting point at which the linker will begin 
looking for the starting point for next section named in the command. 
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5. Ifthe order which the SORDER command specified cannot be maintained 
then the linker will issue a warning and continue trying to assign memory to 
the remaining sections in the SORDER command. 


6. Ifasection named in the SORDER command is missing a waming is issued 
and the linker will continue with the next named section, if any. 


The ORDER command applies to long sections; the SORDER command applies 
to short sections. If a section name appears in these commands for the first time it 
is assigned the appropriate length attribute, but it is assigned neither the common 
nor the noncommon attribute so that subsequently it can be either. 


If the name of a long section appears in the SORDER command, a waming is 
printed and the section is given the short attribute. This can occur if a SECT, 
COMMON, PAGE, CPAGE, or NOPAGE command precedes the SORDER 
command, since these commands assign newly-found sections the long attribute. 


The same section name cannot appear twice in an SORDER command. Multiple 
SORDER commands are accepted withont a waming. They are concatenated and 
must not contain duplicate names. 


The order of sections within each group is specified by entering section names 
separated by commas. Any sections remaining within the group are assigned 
Memory space after the sections specified in the command in the order in which 
their names were encountered by the linker. 


An SORDER command can be continued to the next line by terminating it with one 
or more spaces followed by a pound sign (#). A continuation character must be 
placed like a comma between section names. 


Examples 


ORDER SEC1,COMSEG 
SORDER SEC2, SHORTSEC 


ORDER SECT1 # 
SECT2,SECT3 # 
SECT4 
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START — Specifies Output Module Starting Address 
Syntax 
START value 
Description 


value Specifies the starting address used in the output object 
module. 


The START command specifies the absolute starting address to be placed in the 
terminator record of the object module. If no starting address is specified, the 
starting address is obtained from the END record of the main program of the input 
modules. This record was created using the END directive in the assembler. If no 
main program has been read, the starting address will be zero. 


The START command can be useful if the starting address falls in an absolute 
section or in a relocatable section with a specified load address, In the latter case, 
you should be aware that when the load address is rounded upwards to lie on a word 
or page boundary, the starting address is not likewise rounded, 


Example 


START $7FC 
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UPPERCASE — Shifts Names to Uppercase 
Syntax . 


UPPERCASE [class{,class]...] 


Description 
class Specifies one of the following class names: 
PUBLICS All public and external names. 
MODULES All section names. 
SECTIONS All module names. 


The UPPERCASE command causes the linker to shift names to uppercase on 
input. All symbolic names of the specified class(es) will appear in uppercase in the 
linker’s output files. 


If class is not specified, all classes of names are affected. Each class can have only 
one case specification (i.c., CASE, UPPERCASE, or LOWERCASE). CASE, 
LOWERCASE, and UPPERCASE take immediate effect and should be used 
early in the command file. 


Example 


Given the following command file: 
UPPERCASE PUBLICS 
LISTMAP PUBLICS 


c LOAD modulea, moduleb, modulec 
END 


All public and external names will be set to uppercase in the linker’s output file. The 
generated link map will contain a PUBLIC SYMBOL TABLE section that will show ail 
the upper-case public and external names. 


For example: 


PUBLIC SYMBOL TABLE 


SYMBOL SECTION ADDRESS MODULE 
GL sect3 00001200 MODULEA 
G2 sect3 00001204 MODULES 


G3 sect3 00001208 MODULEC 
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WARN — Modifies Message Severity - UY 
Syntax 
WARN number(,number)... 
Description 
number Specifies a message number. 


The WARN command specifies that the message indicated by number is to be 
treated as a warning. 


This command has a global effect from the point at which the linker processes the 
information contained in the command. A subsequent WARN command overrides 
any values set by a previous one. 


Fatal errors and the errors or warmings that are generated as a result of a 
syntactically or semantically incorrect WARN command cannot be overriden. 


Example 


WARN 325 


Downgrades error condition 325 to a waming. ( ) 
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Introduction 


The linker uses a two-pass process in which the commands and object modules are 
checked for errors. A symbol table is formed during pass one, and the output object 
module is generated on pass 2. 


Emrors detected during the first pass of processing will be displayed on the listing. 
If the linker is executed in batch mode, fatal errors cause the linker to terminate with 
the message Load Not Completed. 


During pass two of processing, the final absolute object module is produced along 
with a link map and a listing of unresolved external references. A local symbol 
table, public symbol table, and cross-reference table map may optionally be listed 
on the link map. The link map also indicates the output module name and format, 
the section and module summary, and the starting address of the load. Detailed 
descriptions of the map file and listings can be found in this chapter. 


Linker Listings 


Figure 12-1 shows the linker command file, and Figure 12-2 shows the output 
listing. Figures 12-3 shows the linker absolute file, while Figures 12-4 to 12-6 show 
the assembler files used. They are used as a reference to describe both the linker 
output listing format and the loading process. 


The main purpose of the linker output is to convey all pertinent information 
regarding the linker process. The listing can also be used as a documentation tool 
by including comments and remarks that describe the function of the particular 
program section. 


Refer to the following points in order to examine and understand the linker listing. 


1. Figure 12-1 shows the command file which includes the following 
commands: 


a, The Carp command ensures that the linked code will run on a 68000 
microprocessor. 


b. The LIstmap and LIsTABs commands in this command file generate 
a symbol table listing of both local and external definition symbols 
and places the local symbols into the output object module. The 
symbol tables will display the symbols along with their final 
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absolute values. You can determine from the link map and symbol O 
addresses as well as from the final object module that modules have 

been correctly linked together to form a final absolute module. All 

addresses will be adjusted to the correct values, and all links 

between modules resolved. 


c. The user has specified the starting address of the section named 
COMSEC. 


d, The oRDER command places the sections in a different order than the 
default. 


€ PUBLIC EXTRANEOUS=$2000 defines the value of the EXTRANEOUS 
symbol to be $2000. 


f. NAME TESTCASE specifies the name of the final output object module 
as TESTCASE. 


g. The link map will show the starting and ending addresses of the 
sections of the three modules in the order loaded. Note that a PAGE 
SECT2 command appears in the linker command file so the link map 
will show that the initial piece of secr2 (from the first module) starts 
on the next page boundary. 


h. The LOAD command will read the three modules from the files ee 


shown. 


i. The END command starts the final steps in the load process. 


2. Figure 14-2 shows the link map which shows the following: 


a. The commands in the linker command file. 

i b. The output module name and the output module format. 

c. The names of all sections followed by the attribute, starting address, 
ending address, length, and type of alignment for each section. 


| d. A module summary containing the names of all the modules 
followed by the starting address and ending address for each section 
in each module. Any executable address errors encountered during 
Pass two of the load are indicated at the end of the module summary. 


3. The unresolved externals section contains a list of the undefined external 
references. 


GQ 
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When the appropriate LISTMAP command options are specified, lists of 
all local symbols and public symbols are displayed in symbol tables. All 
symbols in the map are truncated to 10 characters. Symbols are displayed 
as follows: 


Public symbols as declared in the assembler are external definition symbols 
and are used for intermodule communication. 


Local symbols are those known only to a single module. Local symbols are 
not used by the linker, but are listed so their final absolute values can be 
seen, The attributes and sections are listed for each local symbol, as well as 
the section offsets and modules which define them. Since LIstTmar 
CROSSREF is specified, a cross-reference table is listed. Local symbols can 
be placed in the output object module of the assembler by specifying the 
OPT T directive, and can subsequently be used for symbolic debugging. 


The local symbol table contains two types of symbols: 


¢ High-level elements are compiler symbols whose attribute is Loca. The 
OFFSET column indicates the stack address offset in bytes for each 
section. High level symbols contain both mMopuLE and FUNCTION 
information. 


¢ Low-level elements are assembler symbols whose attribute is ASMVAR. 


OFFSET is the actual section address. Only the MopULE information is 
listed in the local symbol table. 


The public symbol table contains the list of PUBLIC symbols, the section, 
the actual section address, and the modules. 


The cross-reference option is tumed off by default. To produce the cross- 
reference table, use the LISTMAP CROSSREF command. An example of 
the cross-reference table output is shown in the map file after the symbol 
table information. All external symbols passed to the linker are listed under 
the heading symBoL. The symbol section and address are listed. Any flag to 
the left of those values is the section attribute of the symbol. Under mopuLe, 
a module name preceded by a minus sign indicates that the symbol was 
defined in that module. Line numbers not preceded by a minus sign indicate 
a reference to the symbol in that module. 


Next, the starting address of the load is indicated. 


Finally, the end of the load is indicated by the Load Completed or Load 
Not Completed message. In this example, Load Completed is shown. 
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Linker Command File 


1 { CHIP saaBe 
LISTMAP INTERNALS, PUBLICS, CROSSREF 
LISTABS INTERNALS, PUBLICS 
COMMON COMSEC=$ 1889 
ORDER SECT2, SECTS, COMSEC 
PUBLIC EXTRANEOUS=$2088 
NAME TESTCASE 
PAGE SECT2 
* Load first two modules 
LOAD Ink6&6ka.obj, Ink68kb.obj 
* Load last module 
LOAD InkGBkc.obj 
END 


Figure 12-1. Linker Command File 
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be Linker Map File 


Microtec Research LNK6SK Version 6.8 Fri Aug 23 18:93:19 1991 Page 1 


Command tine: ink6Bk -c tst6Bk.opt -Fs -o cmp68k.x -—m 


CHIP Geena 

LISTMAP INTERNALS, PUBLICS, CROSSREF 
LISTABS INTERNALS, PUBLICS 
COMMON COMSEC=$1888 

ORDER SECT2, SECTS, COMSEC 
PUBLIC EXTRANEOUS=$ 2008 

NAME TESTCASE 

PAGE SECT2 

* Load first two modules 
LOAD Ink66ka.obj, Ink68kb.obj 
* Load last module 

LOAD Ink68kc.obj 

END 


Figure 12-2. Linker Map File 


= 
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OUTPUT MODULE NAME: TESTCASE 
GUTPUT MODULE FORMAT: MOTOROLA $2 


SECTION SUMMARY 


SECTION ATTRIBUTE START END LENGTH ALIGN 


SECT2 NORMAL CODE @eesesee §=epee8d225 48880226 2 (VORD) 
SECTS NORMAL CODE @@090226 eeBee23F aanaesiA 2 (WORD) 
SECT1 SHORT DATA eae8a248 eeaeez92 aBgAagass § 2 (WORD) 
ABSOLUTE DATA egesesen §66saaeases §=6apaee@aG ) = (BYTE) 
ABSOLUTE CODE @geai6ea eog810e9 aeBeaaBA @ (BYTE) 
COMSEC COMMON @aei68e e8Ae1e81 eeegees2 2 (WORD) 


MODULE SUMMARY 


MODULE SECTION: START SECTION: END FILE 


MAINI SECT 1: 46880248 SECT1:88080298 9 /test/Ink68ka.ab{ 
788081808 188881083 
SECT2 : BB886888 SECT2: 88868859 


READ SECT 1: @@888292 SECT1:80000292 /test/Ink68kb.ob} 
SECT2: @80606188 SECT2 : 88688189 f° 
COMSEC : 28881688 COMSEC : 88801888 
VERYVERYLO SECT2 88888288 SECT2:88688225 /test/Ink6Bkc.obj VY 
SECT3: 8888226 SECT3 : @808823F 


>BBB86488 7 BB89B485 
COMSEC : 88881088 COMSEC : 86661881 


ERROR: (328) UNRESOLVED EXTERNALS: 


MODULE 
MAINI 


SECTION OFFSET MODULE: FUNCTION 


ABSCONST @@F7@01F MAIN: 
ABSCONST @8F78931 MAIN1: 
SECT2 egeeseeC §=MAIN1: 
ABSCONST @8F78019 MAINi: 
ABSCONST @888862A MAIN1: 
SECT2 64888034 = MAIN1: 
SECT2 eeeegaic = MAINi: 


Figure 12-2. Linker Map File (cont.) 
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PROC @ae01004 
MAIN2 SECT2 easeeaae 
BLNK ABSCONST sagaeani4 
ASCR ABSCONST @@aaa9aD 
LENGTH COMSEC 4a88i668 
READA8 SECT2 98088146 
BSPA ABSCONST @aBeeeds 
COUNT SECT1 aaBee292 
READSE SECT2 eB8881SC 
READ6B SECT2 66088 16C 
READ18 SECT2 @8088104 
READ7@ SECT2 68088172 
TAB ABSCONST e8aeeB09 
READ28 SECT2 69860128 
READEB SECT2 68688170 
BLNK ABSCONST 92090020 
ASCR ABSCONST @6e08080 
READ3@ SECT2 6a80e1398 


PUBLIC SYMBOL TABLE 


SECTION ADDRESS MODULE 
COMSEC 8801888 
SECT2 eeaeeR4e 
‘ ea9aB07F 
SECT 1 ge98Bb298 
EXTRANEOUS eaB802800 


ge INBUF SECT1 oB888248 
i INBUFEND SECT1 ggaa9298 
READ SECT2 49088188 

TIN SECT2 gga9aaic 

TOUT SECT2 anee8834 


CROSS REFERENCE TABLE 


SECTION ADDRESS MODULE 


COMSEC ga901880 «= - $$ 
SECT2 Bae68048 -MAINI 
READ 
geeese7F 6 -$$ 
READ 
88888298 = -MAINI 
READ 
EXTRANEOUS aeea280a = - $$ 
INBUF 84088248 = -MAINI 
READ 
INBUFEND @B888298 -MAINL 
READ @@B88168 -READ 


Figure 12-2. Linker Map File ({cont.) 
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SCAN eaggaeaa 
TIN eaenedic 
TOUT 8880034 


START ADDRESS:  agaagaaa 


Load Completed 


Errors: 1, Warnings: 8 


Figure 12-2. Linker Map File (cont.) 


oF 
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Linker Absolute File 


The absolute output module is shown in this section. In this sample, the output 
object file shown is in Motorola S-Record absolute hexadecimal format. 


$$ TESTCASE 
COMSEC $60a21488 EXTRANEOUS $agaa2eea8 
$$ MAINI 
TIN $@808881C INBUF $@a088248 INBUFEND $@@888298 ECHO $aggae2908 
CRLF $GB888848 BLETE $eBBGEe7F TOUT $enBBadS4 UDATOUT $oBr7eeir 
USTAT $@8F78031 MAIN1@ $@B8B82BC UOATIN $@GF70819 ASLF $eaBBBzeA 
OUTB $@a028834 IND $eB8Ge21C PROC $80881804 MAIN2 SaBeaaeaa 
BLNK $@9888014 ASCR $aggaeeaD 
$3 READ 
READ $02908168 LENGTH $80801882 READ46 $ee880146 BSPA $eeneeeaE 
COUNT $88880292 READS@ $6080815C READE $e800G16EC READ1G@ $ageH010A 
READ7B $08000172 TAB $ea0R8G09 READ2@ $@n008128 READeA $aB8G017C 
BLNK $8@008020 ASCR $009888@D READSA $eaG89138 
$$ VERYVERYLONGMODULENAME 
$$ 
5@9698804844521B 
S26E@0 1gaas6aeeeRe22E7CaeeR 1BeeCS 
$21480808045890080016822700000024012198C1CB 
$214800010031467F 54EB90G0888804E75323900F 730 
5214800820883 10801680166F4 14398@F 74819820205 
$214688838807F4E75323980F 76631080 16008266F481 
$21408884613C260F 7001F4E75149C@GBD4EBAFFEGBS 
S2BEB@B050 143CBGQA4EBAFFDE4E7S9F 
$214980168227008088240427802924EB9aaeaRe1C99 
$2 14808110804 168 1865ea8aRA4ERSaRRBRR486GE076 
$2148881288C4 180806608001 23438029267DC228112 
521490813833C20000 16884E 75004 1497F660RG01E62 
$21488814034380292670453898438880 18292343062 
$2149801SaGea84ER9RaRe08346o0RG818eCe1A8a9C9 ' 
521486016867008aBAGCH 1BB2a60R88088812015278DA : 
$2 148881788292343682920C42005867CA323802901B 
S26E888 18867884ER9eR00003460G065 
$2148882684E7 132398888 1 B68027804984E7193012E 
$2148882180009 108 16AG@0096040100AA1298948302 
$2140882264E714£4F 66FC22708880048039219660088 
821480023809664689000082 1Cagaae2 1Caagaa4eesA 
5320A880409050692104E7189 
$5830015E7 
See4eeea0erF 8 


Figure 12-3. Linker Absolute File 
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Assembly Listings for the Linker Example 


Figures 12-4 to 12-6 show three assembly listings of programs that are combined 
by the linker. The actual load is shown in Figure 12-4, Note the following points 
when examining the assembly listings: 


1, The Marn program contains references to subroutines called READ and SCAN 
that are not in the program but are declared external. scan is not defined in 
any module. The user could have specified the address of scan at load time 
with a PUBLIC command. 


2. The second assembly listing shows the READ module that is required by the 
MAIN program and also shows that READ references the I/O drivers rin and 
tout that are declared external in the Man program. 


3. The third program contains no links to the other programs, but does contain 
absolute code. The common section is used to provide linkage between the 
programs, 
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Command line: asmS8k -1 -a InkSBka.obj Ink6Bka.tst 
Line Address 
1 

This 1g a sample program that demonstrates some of the 
features of the relocatable assembler and linker. 
Three modutes are linked together to form the final 
program. External definitions and references as well 
as COMMON are used to communicate between routines. 


The main program is below, In the main program are 
3/0 drivers that are referenced by one of the routines 
linked to this main program. 


eee ee Hee EO ee 


LLEN 408 
MAIN’ — IDNT 
OPT D,E,T 


XDEF__INBUF , INSUFEND, TIN, TOUT, CRLF, ECHO, DLETE 


1 KREF READ, SCAN 
2 
SECT.S SECT1 
egengaea INBUF 0DS.8 88 jInput buffer 
INBUFEND jEnd of buffer 
epaaeese ECHO 03.8 1 jEcho flag 
* 
ae ORG $1088 


aia 98881808 6888 Beea2 BRA PROC : 
3 2981804 2E7C aaad 1888 PROC MOVE.L #$1688,SP ;Set stack 
* 


SECT SECT2 
aaasseee 4ER9 BaBs Baae MAIN2 JSR READ ;Read next line 
ageseees 227C Bees Baae R MOVE.L  #INBUF,A1 gStart of buffer 
BaaeBesc 1219 MAIN1@ MOVE.B (A1)+,D1 
B8e8BGBE BCA1 8814 CMP.B = #BLNK,D1 ;Check for non-blank 
68806@12 B7FB BEQ MAINIB 
6088814 4EB9 agea Bage ISR SCAN ;Get value 
BBB8881A 4E75 RTS 


NAME = -_«OING 
THIS ROUTINE WILL READ A CHARACTER FROM THE TERMINAL 
ENTRY PARAMETERS 


NONE 


o*@ ep eee enn 


EXIT PARAMETERS 


02 - INPUT CHARCTER 


Figure 12-4. Assembly Listing 1 
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Line Addrass 
age88e1C Q@SF7 8831 
69888822 ee1 
88898026 
8008828 @8F7 8819 
6ua88a2E @67F 
8988832 


68000834 3239 8GF7 8631 
BB88083A 8801 BAEZ 
@BBB893E GEFS 

68888048 13C2 8aF7 BO1F 
BBBBEE46 4E75 


@BABBB48 143C 
BOBGABAC 4EBA 
0880858 143C 
G88880S4 4EBA 
8886858 4E75 


@OF76@31 
@3F7401F 
6@F 78019 
eeegeaaD 
G8e0808A 
89888614 
88a6807F 
@aageeiC 
aaanees4 
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;Read UART status 
;Check if raady 
jNot ready yet 
;Read data 

jDelete parity bit 


INS MOVE.W-«USTAT, D1 
BTST.L #$1,D4 
BNE INB 
MOVE.B  UDATIN, D2 
ANDI.8 #DLETE,D2 
RTS 

NAME - OUTS 

THIS ROUTINE IS USED TO WRITE A CHARACTER TO THE TERMINAL 

ENTRY PARAMETERS 

02 - CHARACTER TO OUTPUT 

EXIT PARAMETERS 


NONE 


znouune ne ween eee 


ouTé MOVE. USTAT,DL 
BTST.L #2,D1 
BNE oura 
MOVE.B 02,UDATOUT 
RTS 


Read status 
;Check if ready 
3Not ready 
;Output data 


* 
2 NAME - CRLF 


a. 
® THIS ROUTINE OUTPUTS 4 CARRIAGE RETURN AND LINE FEED 
= 
* 


CRLF MOVE.B #ASCR,02 
JSR OUTS 
MOVE.B #ASLF,D2 
ISR Gure 
RTS 


EQu $F7¢031 
EQU $F7@01F 
EQuU $F7@019 
EQU 
EQU 
EQU 
EQU 
EQU 
EQu 
END 


;UART status 
3Serial output port 
3Serial input port 


Figure 12-4. Assembly Listing 1 (cont. 
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Symbol Table 
Label Value 


ASCR 6888680 
ASLF aeBaaeaA 
BLNK 6800814 
CRLF SECT2: 88980848 
DLETE Gee0B887F 
CHO SECT1: 88088056 
INS SECT2:8900081C 
INBUF SECT 1:6@00G888 
INBUFEND SECT1:88080856 
MAINI@ SECT2; seg088aC 
MAIN2 SECT2: aagepeae 
OuTB SECT2: 9080034 
PROC 66881884 
READ External 
SCAN External 
TIN SECT2; ape@e@881iC 
TOUT SECT2: aagaa834 
» UDATIN @aF 78819 
UDATOUT BOF 7081F 
USTAT BeF78831 


Figure 12-4. Assembly Listing 1 (cont.) 
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Command ine: asm68k -1 -o Ink66kb.obj Ink6Bkb.tst 


Line Address 


eaeaaGes 


gogeeeea 227C 
88088886 4278 
eeeaeasA 4EBS 
8688910 8041 
68088814 6688 
@8888818 4£89 


@BeB891E BEB 


088 BaBa 
aeaa 
9688 8860 
a816 
@BBA 
gabe 8288 


e8e0e026 BC41 BRED 
eenaesg24 668G BB12 
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eee eR RH He eee 


E READ 
R 


READ2@ 


NAME - READ 


THIS ROUTINE READS IN A LINE FROM THE TERMINAL AND 
PLACES IT INTO THE INPUT BUFFER. THE FOLLOWING 
SPECIAL CHARACTERS ARE RECOGNIZED: 


CR ~ END OF LINE 
CONTROL X - DELETE CURRENT LINE 
DEL - DELETE LAST CHARACTER 


ALL DISPLAYABLE CHARACTERS BETWEEN BLANK AND DEL 
EXCEPT FOR THE ASOVE SPECIAL CHARACTERS ARE 
RECOGNIZED BY THIS * ROUTINE, AS WELL AS THE TAB. 
ALL OTHER CHARACTERS ARE IGNORED. AN ATTEMPT TO 
READ HORE CHARACTERS THAN ALLOWED IN THE INPUT 
BUFFER WILL BE INDICATED BY 4 BACKSPACE. 


ENTRY PARAMETERS 
ECHO - ECHO FLAG, @= NO ECHO 
EXIT PARAMETERS 


INBUF - CONTAINS INPUT LINE 


D,E,T 
READ 

CRLF, TIN, TOUT 

INBUF, TNBUFEND ECHO, DLETE 


SECT.S SECT1 
0S.8 1 


SECT SECT2 © 


MOVE.L #INBUF AL 


COUNT 


E READ1a TIN 


#24,01 
READ28 
CRLF 


READ 
#ASCR,O4 
READIO 


Figure 12-5. Assembly Listing 2 
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Line Address 
eaageeze 
eea8282C 
ee08802E 
eengae3e 
eeneR836 
baaeea38 
peaesasc 
eananeda 
eaeeee44 
geneae4s 
eeagae4s 
GB2BB04E 
geaeaas2 
aeeene5e 
eeoe885C 
eapeee6a 
eengaRss 
eaaeassa 
eeceagec 
BeeaseGe 
aeaRea?2 
eaae2076 
BBB8887A 
geeaae7C 
aoaenssa 
eaaBeen2 
panegesa 


Begeneae 
geeeaaeD 
aageeea8 
eeaaee2e 
eeReaess 
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3438 
6700 
2264 
332 
4E75 
@C81 
6688 
3438 
6704 
5389 
8438 
349C 
4EB9 
6888 
acei 
6788 
acai 
§0a8 
12C1 
§278 
3438 
BC42 
67CA 
3298 
6788 
4E89 
6888 
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eae 


Bbe8 8688 R 


9880 
@B1E 
9688 


E READ3IB 


6861 
6088 
e808 
9018 
eeB9 
B@BA 
8828 
9888 


READS@ 


READEB 
R 


aaa8 
agag 
9058 


R READ?7@ 


8888 E— READBA 


@ea8 eabe E 
* PLACE 


LENGTH 
ASCR 
BSPA 
BLNK 
TAB 


Assembly Listings for the Linker Example 


Frt Aug 23 16:33:87 1991 


VARTABLES 
COMMON 
DS.B 

EQU 

EQU 

EQU 

EQu 

ENO 


Page 2 


COUNT , D2 
READ10 
D1, (AL) 
D2, LENGTH 


#0LETE,D1 
READSA 
COUNT , D2 
READ1G 
#1,A1 
#1, COUNT 
#BSPA,02 
TOUT 
READ7@ 
#TAB,D1 
READE 
#BLNK,O1 
READ74 
01, (A1)+ 
#1, COUNT 
COUNT , D2 
#88,D2 
READ4@ 
ECHO, D1 
READIG 
TOUT 
READ10 
IN COMMON 
COMSEC 


Figure 12-5. Assembly Listing 2 (cont.) 
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Label 


ASCR 
BLNK 
BSPA 
COUNT 
CRLF 
OLETE 
ECHO 
INBUF 
INBUFEND 
LENGTH 
READ 
READ16 
REA0Z@ 
READSB 
READ48 
READ5S@ 
READEB 
READ?78 
READE@ 
TAB 
TIN 
TOUT 


Symbol Tabte 
Value 


eeageeeD 
96680828 
ebeanaes 
geesecaa 
External 
External 
External 
External 
Extarnal] 
@eebea8e 
: 90808888 
:8a8ge884 
:48888828 
168888838 
:B88B8846 
:@Q88G85C 
:8B8G8B6C 
:08088872 
:8988887C 
egeeaae9 
External 
External 


Figure 12-5. Assembly Listing 2 (cont.) 
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Command line: aem68k -1 -o Ink&Bkce.obj InkGBkc.tst 
Line Address 


* NAME - VERYVERYLONGMODULENAME 
x 

* THIS ROUTINE DOES NOT HAVE ANY EXTERNAL 

* REFERENCES TO THE OTHER MODULES, BUT 

* CREATES SEVERAL RELOCATABLE SEGMENTS 

* AND IS LINKED WITH THEM FOR DEMONSTRATION 
* PURPOSES, 


VERYVERYLONGMODULENAME IDNT 
OPT € 


* Create a Relocatable Section 
* 


SECT SECT2 
eeeagees 4E71 NOP 
Bengeae2 3239 esas Bee R MOVE.W LEN1,D1 
gasesees D278 40g 4E71 ADD DATA, 01 
BBGGQ9BE 33C1 BBB Baal A MOVE D4, LEN2 
apegaei4 GABB Bees BPLsLABA 
8BB88018 @ABi BaAA EORI.8 #$AA,D1 
@BBBB81C 1238 B483 4E71 —LABL ~«=- HOVE. DATAs3,01 
i @a08a822 4E4F LABS TRAP #15 
CN 8088824 G6FC BNE LAB 
x 
oot . « Create a Relocatable Section 


a 


SECT SECTS 
88888088 227C BBBe B4a8 MOVE.L #0ATA,A1 
88888886 3219 MOVE (At)+,D1 
Begeseee 66ae anes BNE SKP 
@BeeeeaC 4EBS Bea aAiC R ISR LABi 
@@BaaB12 Beee BGiC oC.L LAB1L 
baee8816 Baae B40 DC.L DATA 


* Create an Absolute Section 
. 
ORG $482 
eanee4e8 DATA OC.B 5,6 
aesae4s2 de LABL 
98800484 nop 


e 
* Place variables in COMMON 
. 


COMMON COMSEC 


aseasece LEN1 DS.B 1 
aBaeeee1 LEN2 OS.B 1 
END 


Figure 12-6. Assembly Listing 3 
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Symbol Table 
Value 


| ganeedaa 
t SECT2 :aane@aic 
SECT2 :ea988e22 
| COMSEC ; Bagaaen8 
COMSEC: 88080681 
SECTS :e8¢80812 


Figure 12-6. Assembly Listing 3 (cont.) 
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The LIB68K Object Module Librarian builds program libraries, which are 
collections of relocatable object modules residing in a single file. These libraries 
cause the linker to automatically link frequently-used object modules that define 
public symbols which are referenced in other linked modules. These modules are 
linked without concern for the specific names and characteristics of the modules in 
which the symbols are defined. The LIB68K Object Module Librarian features 
include: 

¢ Creation of librarians that can be read by the linker 

¢ Ability to add, delete, or replace individual modules in a library 

¢ Ability to display library directories 

+ Case-sensitivity for symbol] names 

¢ Batch command line input and return codes for make-type utilities 

* Interactive operation 

¢ Optimized library structure for fast access during link time 


This chapter describes how to build and modify the libraries and how the linker uses 
the libraries. 


The word ‘‘module’’, when used in discussing the librarian, refers to a relocatable 
object module that results from assembling a source program with the 
ASM68KRelocatable Macro Assembler. 


Error messages and warnings are listed in Appendix D, Librarian Error Messages. 


Librarian Function 


The librarian formats and organizes library files that will subsequently be used by 
the linker. Libraries provide a convenient means for managing collections of 
relocatable object modules and a more efficient means for linkers to access the 
modules when required. This efficiency is realized by reducing the number of files 
that must be opened for linking modules. 


When writing modular programs, communication among the various modules is 
established through the use of PUBLIC and EXTERNAL symbols. For example, 
the following illustration in Figure 13-1 shows three relocatable object modules that 
resulted from an assembly. 
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IDNT *SQUARE' 
PUBLIC - NEXT 
EXTRN FALLOW 


+ Program Module 1 


FALLOW 


IDNT ‘SINCOS' 
PUBLIC FALLOW 
EXTRN NEXT 


7 Program Module 2 
8 


NEXT 


IDNT ‘ARCTAN' 
PUBLIC ARCTAN 


* Program Module 3 


LOAD R1, 26008 
MULT R1,R2 
NOP 

END 
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A relocatable object 
module that resides 
in host system file 
KNEWEL.OBJ 


A relocatable object 
module that resides 


in host system file 
SWIGGET.OBJ 


VU 


A relocatable object 
module that resides 
in host system file 
BAYER.OBJ 


Figure 13-1. Three Relocatable Object Modules Resulting from Assembly 
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Of the three modules shown, Program Modules 1 and 2 communicate with one 
another through external references and public symbols, while Program Module 3 
is a stand-alone module. 


The relocatable modules illustrated consist of load data information, relocation 
information, and records that indicate public symbols and external symbols. 


By using various combinations of librarian commands, the relocatable object 
modules shown can be made members of a library. There are three ways to invoke 
the LIB68K Object Module Librarian: 


1. Using the command line. 


Only certain library functions can be specified using this method: 
ADDMOD, DELETE, REPLACE, EXTRACT, and FULLDIR. These 
librarian commands can be entered in any order, but the librarian processes 
the commands in the order specified above. 


2. Reading librarian commands from a command file in batch mode. 


The commands are read in the exact order in which they are specified. If an 
error is found, commands read after the first error is encountered are 
processed, checked for errors, and executed if possible. However, a library 
file, if specified, is not generated. 


3. Entering librarian commands interactively from the terminal. 


When an illegal command is entered, the librarian displays an error 
message and provides an opportunity to re-enter the command. In this 
interactive mode, most librarian command errors are not fatal. 


For example, a new library can be created by using the following commands: 


CREATE NEWREM.LIB 
ADDMOD KNEWEL.OBJ 
ADDMOD SWIGGET, BAYER 
SAVE 


Now the library can be used by the linker. 


Assume that you have written a program module called main. After MAIN has been 
assembled, the resultant relocatable object module in Figure 13-2 is in a host system 
file named MAIN. OBJ. This module has a reference to the public symbol arcran. 
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EXTRN ARCTAN 


A relocatable object 
module that resides 
in host system file 
MAIN.OBJ 


; Main Module 
NOP 
CALL ARCTAN 
NOP 
END 


Figure 13-2. Relocatable Object Module in MAIN.OBJ 


Before the library existed, you could have directed the linker to load the Mary 
module and the module that contains the reference to ARCTAN. 


LOAD MAIN.OBJ 
LOAD BAYER.OBJ 


After the library has been created as previously shown, you can direct the linker as 
foliows: 


LOAD MAIN. OBJ 
LOAD NEWREM. LIB 


The linker will access the library to try to resolve external references such ‘as 
ARCTAN. The MAIN module can be modified so it calls the stINcos module as well 
(see Figure 13-3): 


EXTRN ARCTAN 
EXTRN FALLOW 
A relocatable object 
? Main Module module that resides 
in host system file 
CALL ARCTAN 
cae pace MAIN.OBJ 


END 


NOP 


Figure 13-3. MAIN Module Modified to Call SINCOS Module 


Without the ability to load from a library, it would be necessary to command the 
linker as follows. 


LOAD MAIN.OBJ 


LOAD SWIGGET.OBJ 
LOAD BAYER.OBJ 
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However, when using a linker that has the ability to load from a library, you need 
specify only: 


LOAD MAIN 
LOAD NEWREM.LIB 


The linker will load the relocatable object module Marn in the usual way. It will load 
the other modules from the library referenced by MAIN. 


The following example is a more practical illustration of using the library. 
Example: 


Suppose you write a series of program modules consisting of a number of 
mathematical routines including a few modules that calculate transcendental 
functions. These modules are then gathered into a library file through the use of the 
LIB68K Object Module Librarian. 


Sometime later, you need to calculate an arc-tangent function within a program 
being written. You are aware of the fact that there is an arc-tangent function in a — 
library file, and you know the name of the entry point of the routine. You also know 
how to pass parameters to the arc-tangent function and how to accept the result of 
the calculation. 


You need only do the following: 


1. CALL the arc-tangent function from the program being developed, placing 
‘the public name of the entry point into the argument field of the CALL or 
JUMP instruction. 


2. Place the public entry point name of the arc-tangent function in the 
argument field of an external reference (KREF) pseudo-op in the program 
being written. 


Even though you do not know the name of the relocatable object module that 
contains the arc-tangent function, you can include the correct relocatable object 
module by informing the linker to use the required library file. 


You do not have to specify which module contains the arc-tangent function. The 
linker automatically searches the named library. It looks for the entry point name 
coded as the argument of the CALL statement. When the entry point name has been 
found, the linker identifies the module in which it resides and then includes the 
module containing the name in the current load. 


The linker determines which of the library modules to use by examining the internal 
list of unresolved external references accumulated during the link process. It then 
accesses the library file to determine if there is a match between unresolved external 


Microtec Research, Inc. 13-5 


Return Codes 


Librarian Operation 


references, and a label or name that has been declared public in the library file 
modules. The linker then identifies which modules contain the matching public 
symbols and includes those modules just as if you had explicitly directed the linker 
to load the proper modules, 


When the inclusion of a module in the library adds an undefined reference to the list 
of undefined references, the linker will access the library again until all external 
references have been satisfied. All public symbols within a library must have 
unique names. 


Return Codes 
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The librarian provides operating-system specific retum codes. The librarian either 
completes without encountering an error, displays a message or warning, or 
terminates with an error. Error messages and warnings are listed in Appendix D, 
Librarian Error Messages. Return codes are described in the Microtec Research 
ASMO68K User’ s Guide. 
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Introduction 


This chapter describes the commands used by the LIB68K Object Module 
Librarian. The librarian reads a sequence of commands from the command input 
device in interactive or batch mode. The command sequence must be terminated by 
the END command. Relocatable object modules are read as input and collected in 
organized libraries as specified in the command input file. 


Multiple sessions are permitted through the use of commands. A session is a list of 
commands before a CLEAR command. It does not end until this command is given. 
The END command terminates the current session and exits the librarian. 


Librarian Commands 


The following pages describe the librarian commands. An alphabetical listing of the 
librarian commands is shown in Table 14-1. 


Table 14-1. Alphabetical! Listing of the Librarian Commands 
Cy Command Abbreviation Function 


Adds module(s) from another library. 
Adds object module(s) to current 
library. 

Clears library session since last SAVE. 
Defines new library. 

Deletes module(s) from current library. 
Lists library modules. 

Terminates librarian execution. 


Copies library module to a file. 
Displays library or library module 
contents, 


Displays context-sensitive command 
syntax. 

Opens an existing library. 

Replaces library module. 

Saves contents of current library. 


O 
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Module names are written according to the rules for the ASM68K Cross Assembler 
used to create the relocatable object modules. Each module must have a unique 
name. Public symbols are written according to the same definition as in the 


assembler. 


The librarian recognizes six special characters listed in Table 14-2. 


Tabie 14-2. Special Characters In the Librarian 


Character Description 


asterisk 
semicolon 


comma 


left parenthesis 
Tight parenthesis 
plus 


The special characters perform the following functions when used in a library 
command line: 


14-2 


The asterisk (*) or semicolon (;) places a comment in a command 
sequence. The librarian ignores the rest of the line following these 
special characters. The librarian does not process comments; it writes 
them to the output file. 


The comma (,) separates members of a list of similar elements. The list 
can contain module names or module file names. 


The left and right parentheses ( }, used in pairs, denote a list of similar 
elements in a command. Parentheses can be used to group module 
names that are members of a library only. 


The plus sign (+) followed by a carriage return acts as a continuation 
character by allowing you to continue a list on one or more subsequent 
lines. Care should be exercised when using line continuation: Do not 
break up or interrupt a complete syntactical unit such as a file name, a 
module name, or a command. The command verb must be terminated by 
a blank if it is an argument. If the continuation character is used 
immediately after the command verb, it must be separated from the 
command by at least one blank. Except as noted above, the line 
continuation character can appear anywhere in a command. 
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C Blanks 


Except as noted above, blanks can be used freely within commands (between 
syntactically-identifiable units). 


Example: 
DELETE MOD1 , MOD2 
is the same as: 


DELETE MOD1,MOD2 


Command File Comments 


Comments can be included in a command file to document the processing. These 
are included by using the semicolon (;) or asterisk (*). 


Example: 
3 This is a complete line of comment. 
addmod modulea.ob} ; This is a command line comment. 
addmod moduleb * This is another comment. 


© 
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ADDLIB — Adds Module(s) from Another Library 
Abbreviation 
ADDL 
Syntax 
ADDLIB library_filename | (module_name[,module_name)...)} 
Description 
library_filename Specifies the library where the named modules reside. 


module_name The relocatable object module(s) that will be added to the 
library named in a previous OPEN or CREATE command. 


The ADDLIB command adds one or more object modules from one library to the 
library currently being created or modified. You can include the entire library by 
entering the library filename and no module names. 


An OPEN or CREATE command must precede the ADDLIB command and name 
the library to which the object modules will be added. ( 


Related Commands 
CREATE, OPEN 
Example 
OPEN LIBRARY1.LIB 
ADDLIB MATH.LIB (SQUARE, SQROOT} 


SAVE 


In the example above, LIBRARY1 is opened. The ADDLIB command adds the 
modules named souarE and soroot from the library MATH. LIB to LIBRARY2.LIB. 


-~ 


O 
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ADDMOD — Adds Object Module(s) to Current Library 


Abbreviation 


ADDM 


Syntax 


appMon filename | ,filename}... 


Description 


filename Specifies the file to be added to the library named in the 
OPEN or CREATE command. 


The ADDMOD command adds a non-library file containing one or more | 
relocatable object modules to the library named in a previous OPEN or CREATE 
command. 


The module(s)} added to the library should have been named at assembly time with 
the NAME directive. The OPEN or CREATE command must precede the 
ADDMOD command. 


Related Commands 


CREATE, OPEN 


Example 


OPEN LIBRARY2 . LIB 
ADDMOD MATH.MBR 
SAVE 


In the example above, the AppMop command adds the file MATH. mBR to the library 
named in the oPEN command, LIBRARY2 . LIB. 
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CLEAR Librarian Commands 


CLEAR — Clears Library Session Since Last SAVE ro 
Abbreviation 
CL 
Syntax 
CLEAR 
Description 


The CLEAR command clears all commands that have been entered in the current 
library session since the last SAVE command. 


Related Commands 
SAVE 
Example 


OPEN LIBRARY2 . LIB 
ADDMOD MATH.O 


SAVE : 
OPEN WRONG _LIB.LIB 

ADDMOD FONT.O 

CLEAR 


OPEN LIBRARY3 . LIB 


In the example above, CLEAR must be executed before opening and processing 
LIBRARY3.LIB. 


” O 
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By CREATE — Defines New Library 
Abbreviation 
CR 
Syntax 
CREATE library_name 
Description 
library_name Specifies the name of the library file being created. 


The CREATE command defines a new library. Naming conventions should follow 
those of your host computer and operating system. 


You can create only one library at a time. A newly-created library must be saved 
before a second one is created. 


It is an efror to add, replace, delete, or extract modules from a non-existent library. 

It is also an error to create an existing library. If library_name exists in the current 

directory, a warning message will be issued in interactive mode; in batch mode, an 
-_~ error will be issued and the new library will not be saved. 


Related Commands 
None 

Example 
CREATE TEMPOR.LIB 


’ Inthe example above, the command CREATE TEMPOR.LIB creates a library file 
called TEMPOR. LIB. 


If TEMPOR.LriB already exists, a warming is displayed in interactive mode. When 
using the librarian in batch or command line mode, and you name an existing library 
with the CREATE command, the librarian issues an error message. No library is 
created, 


O 
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DELETE 


DELETE — Deletes Module(s) from Current Library 


Abbreviation 
DE 
Syntax 
DELETE module_name(,module_name}... 


Description 


module_name Specifies the name of the module to be removed from the 
library named in a previous OPEN or CREATE command. 


The DELETE command removes one or more relocatable object modules from the 
library named in the OPEN or CREATE command. Object module names are 
case-sensitive, 


An OPEN or CREATE command must precede DELETE. 
Related Commands 
CREATE, OPEN (3 
Example : 


OPEN LIBRARY3.LIB 
DELETE ARCTAN, SQUARE, RAD 
SAVE 


In the example above, the pELETZ command deletes relocatable object modules 
named ARCTAN, SQUARE, and Rap from the library named LIBRARY3.LIB. 
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’ DIRECTORY — Lists Library Modules 


Abbreviation 

DI 
Syntax 

DIRECTORY library_name | (module_name|,module_name]...)} [list_filename) 

Description 

library_name Specifies the name of the library whose module names and 

sizes are to be listed. 
module_name Specifies the name of the module whose size is to be listed. 
list_filename Specifies the directory information will be written to the 


named file. If not specified, the output defaults to the 
standard list device, usually the terminal. 


The DIRECTORY command lists both the module names and the sizes of the 
modules in the specified library. The sizes listed are the number of bytes required 
to store the modules on the host computer system. If you enter just the 
library_name, all modules are listed. If you enter specific module_names, directory 
information is displayed for the named modules only. Full file specification, 
including the path name, can be included for the desired library directory. 


Object module names are case-sensitive. 
Related Commands 

FULLDIR 
Example 

DIRECTORY SIEVE.LIB 


Using the above command, all modules in stevE.1L18 and their sizes are listed: 


Library SIEVE.LIB 


Name Size 
SIEVE .... 1812 
MODULE ... 228 
MODULE1 .. 1032 


Module Total = 3 
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END / QUIT — Terminates Librarian Execution ) 
Abbreviation 


EN 
Q 


Syntax 


END 
QUIT 


Description 


The END or QUIT command terminates librarian command processing without 

building a new library. 

Unless you issue a SAVE command, the librarian will not build a new library. 
Related Commands 


SAVE 


Example ( ) 


LIB68K 
LIST NEW. LIB 
END 


In the example above, the librarian lists the contents of the library New. 115. The =ND 
command exits the library. Since there is no SAVE command, a new library is not 
built. : 
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EXTRACT — Copies Library Module to a File 


Abbreviation 


EXT 


Syntax 


EXTRACT module_name{,module_name)... 


Description 


module_name Specifies the module to be copied from the library named in — 
a previous OPEN or CREATE command, 


The EXTRACT command copies a library module to a file outside the library. The 
extracted module contains the host-specific path and file name specification in the 
same format as that generated by the assembler. Consequently, it can be explicitly 
loaded. 


An OPEN or CREATE command must precede the EXTRACT command. 


Related Commands 


CREATE, OPEN 


Example 


OPEN LIBASC.LIB 
EXTRACT MODA, MODB, MODC 


In the example above, the modules mopa, MopB, and Mopc are extracted from the 
cutrent library and written to files with the same names outside the library. Since 
file name extensions have not been specified, default extensions are appended to the 
file names. The file names created for this example are MODA. OBJ, MODB. OB, and 
Mopc .OBJ. File name extensions, listed in the Microtec Research ASM68K User's 
Guide, are operating-system specific. 
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FULLDIR Librarian Commands 


FULLDIR — Displays Library or Library Module Contents ‘o 
Abbreviation 
| F 
Syntax 
FULLDIR library_name{ (module_name(,module_name|...}1 (list_filename| 
Description 
library_name Specifies the library file whose contents are to be listed. 
module_name Specifies the module whose contents are to be listed. 
list_filename Writes the directory display information to the named file. If 
not specified, the output defaults to the standard list device, 
usually the terminal. 


The FULLDIR command requests a full directory display of a library’s contents 

including module names, their sizes, and all external symbol definitions and 

references. The sizes listed are the number of bytes required to store the modules on - 

the host computer system. ( ) 


If you enter just the library_name, the contents of all modules are listed. If you enter 
specific module_names, information is displayed for the named modules only. 


Related Commands 


DIR 
Example 
FULLDIR TRIG.LIB (ARCSIN, TANGEN) TRIG.LST 


In the example above, the librarian displays information about the modules arcsIN 
and TANGEN, which are members of the library named TR1G.L1B, The output listing 
is written to the file named TRIG. LST. 


The contents of this file are shown below: 


O 
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Library being built trig.lib 


Module Size Processor 
test... 414 68000 


week** PUBLIC DEFINITIONS ****** 
testl 
test2 
test3 
test4 


akkhkke EXTERNAL REFERENCES kkekkKK 
varl 
var2 
var3 
var4 
varS 


Public Count = 
External Count = 
Module Count - 


roe 
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HELP Librarian Commands 
HELP — Displays Context-Sensitive Command Syntax Q 
Abbreviation 
H 
Syntax 
HELP 
Description 
The HELP command gives a list of commands with the correct invocation syntax. 
HELP is context-sensitive. The commands displayed are only those that can be 
legally entered at the time you type HELP. 
Related Commands 
None 
Example 
1ib68k> help a 
CLEAR 
CREATE library name ; 
DIRECTORY library_name[(module_name[,...])] [list_filename] , 
END 
FULLDIR library name[ (module _name[,...])]} [list_filename]} 
HELP 
OPEN library_name 
SAVE 
1i68k> open rp005.1lib 
68k> help 
ADDLIB library name[module_name[,;...]] 
ADDMOD filename[,...] 
CLEAR 
DELETE module_name[,...] 
DIRECTORY library name[ {module name[,...])] [list_filename] 
END 
EXTRACT module name[,...] 
FULLDIR library name[(module_name[,...])] [list_filename] 
HELP 
REPLACE filename[, filename] 
SAVE 
Lib68k> end 
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2 
OPEN — Opens an Existing Library . 
Abbreviation 
OP 
Syntax 
OPEN library_name 
Description 
library_name Specifies the name of the library file to be opened. 


The OPEN command lets an existing library be referenced in conjunction with 
succeeding commands that add modules, delete modules, or replace modules. Only 
one library can be opened at a time. 


If you create a new version of the library, the updated library will have the same 
name as the current library. 


If the library cannot be located or opened for input, an error is reported, In batch 
mode or command-line entry, execution is terminated. 


Related Commands 
CREATE 
Example 
OPEN MATH.LIB 


In the example above, the library named MaTH.1L18B is opened. 
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REPLACE — Replaces Library Module 


14-16 


Abbreviation 


R 


Syntax 


REPLACE filename | ,filename]... 


Description 


filename Specifies a file containing one or more modules that will 
replace the module of the same name in the library named in 
the OPEN or CREATE command. 


The REPLACE command replaces one or more library modules with one or more 
non-library object modules with the same name. The replacement object module 
must have the same name as the library module it replaces. 


REPLACE is not the same as DELETE mod1 followed by ADDMOD mod1 
because ADDMOD always puts the new module at the end of the library whereas 
REPLACE retains the original module order. If the module does not already exist 
in the library, a warning is issued and the module is appended to the end of the 
library. 

REPLACE must be preceded by an OPEN or CREATE command. 


Related Commands 


ADDMOD, CREATE, DELETE, OPEN 


Example 


OPEN LIBRARY1.LIB 
REPLACE SENTIN.OBJ, MODU1.OBT 
SAVE 


In the example above, the oPEN command opens the library LIBRARY1.1L1B. The 


library modules sENTIN.oBJ and MopU1 . OBJ are replaced by non-tibrary modules 
of the same name. 
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Oo SAVE — Saves Contents of Current Library 
Abbreviation 
S 
Syntax 
SAVE 
Description 


The SAVE command saves the contents of the library being created or modified. 
During this time, ADDMOD, ADDLIB, DELETE, and REPLACE commands 
are processed. Although these commands were checked for correct syntax and 
module existence at the time they were entered, the specified modules are not 
added, deleted, or replaced until a SAVE command is issued. 


Related Commands 
END 


Example 


CY CREATE NEW. LIB 


- ADDMOD REL1.OBJ, REL2.OBJ 
ADDMOD FORTUN.OBJ 
SAVE 


In this example above, NEW.L1B is a newly-created library comprised of the 
relocatable object modules named REL1. OBJ, REL2 . OBJ, and FORTUN. OBJ. 


(> 
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Overview 


The example librarian test programs and output listings in this chapter describe the 
input command file and the output listing format. 


The sample test programs in this chapter use command files and object module files. 
Figure 15-2 shows the command file and output listing for the first librarian sample 
program. Figures 15-3 and 15-4 show them for the second sample program. 


During interactive program execution, the information is displayed at the terminal. 


When the librarian is executed in batch mode, the information is displayed in an 
output stream formatted like the output listings shown. 


Librarian Sample Program 1 


The sample program 1 output listing is shown in Figure 15-1. The output listing 
contains the following information: 


( \ 1. The command file is listed. 


2. Anew library, 1ibtest1.1ib, is created based on the CREATE command 
in the command file. ; 


3. Two modules, Lib68ka.obj and 1ib68ka.ob4j are added to this library. 
4. The contents of the library are then listed with the fulldir command. 
5. Each module name, the module’s public definitions, and external 


references are listed. 

6. The total public symbol count and external symbol count are listed for each 
module. 

7. Total module count as well as total warnings and errors if any are displayed 
at the end of the listing. 


O 
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Microtec Research LIBSBK Fri Aug 23 18:45:47 1991 


Version 18.1 


* This test adds modules into a new tibrary and lists 
* them out to confirm correctness. 


cr testi.Jib 
addmod 1{b68ka.obj 
addmod 11068kb.o0bj 
ist test1.lib 
Microtec Research LIBG8K ¥ 16.1 Fri Aug 23 18:45:47 1991 


Library being built test1.lib 


Module Size Processor 
moda ... 387 68888 


eeeeee PUBLIC DEFINITIONS *#*¥#2 
moda_nine 
moda_ten 


weeeee EXTERNAL REFERENCES ***#0¥ 

moda_five 
mhoda_tuo 
moda_ four 
moda_three 
moda_seven 
moda_six 
moda_etght 

joda_one 


Public Count = 
External Count = 


2 
8 


Module Size Processor 
modb ... 387 68088 


sexaez PUBLIC DEFINITIONS *#*0%% 
modb_nine 
modb_ten 


Figure 15-1. Librarian Sample Program 1 Output Listing 
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eaeses EXTERNAL REFERENCES *#*880 

madb_f ive 

modb, tuo 

modb_four 

madb_three 

modb_seven 

modb_six 

modb_eight 

modb_one 


Public Count 


x na Qun 8 
Module Count 
end 


Figure 15-1. Librarian Sample Program 1 Output Listing (cont.) 
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Librarian Sample Program 2 


The sample program 2 output listing is shown in Figure 15-2. The output listing 
contains the following information: 


15-4 


1. 


The command file is listed with error or waming messages following any 
commands that could not be executed. , 


A new library, 1ibtest2.1ib, is created based on the CREATE command 
in the command file. 


Two modules, 1ib68ka.obj and 1ib68kb.obj are added to this library. 


A replacement is attempted on library module 1ib68kd. obj. However, the 
module is not in the library, so a warning message is issued indicating the 
module was not found. The module is then added to the library. 


The contents of the library are then listed with the fulidir command. 


The output listing shows each module name, the module’s public 
definitions, and external references. 


The total public symbol count and external symbol count are listed for each 
module. 


The total module count as well as total warnings and errors if any are 
displayed at the end of the listing. 
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C 


Microtec Research LIBB&K Fri Aug 23 16:45:57 1991 


Version 14.1% 


* create a Hibrary and add three modules trying to replace one with the 
* one that doesn’t have the same name of any present. 
® This should cause an error or warntng. 


1 create test2.tib 
addmoad 141bG6ka.obj 
addmod 14b68kb.obj 
4 replace 11b68kd.obj 
(281) Module modd not found 
WARNING: (211) Module modd added. 


Fri Aug 23 18:45:58 1991 


2 Library being built test2.1ib 


Module Size Processor 
moda ... 387 68888 


3, 5,6 eaeaee PUBLIC DEFINITIONS #o8#9# 
moda_nine 
moda_ten 


seeses EXTERNAL REFERENCES o**#* 
: moda_five 
a. moda_two 
{ moda_ four 
moda_three 
moda_seven 
moda_six 
moda_eight 
moda_one 


Public Count = 
7—_ External Count = 8 . 


Figure 15-2. Librarian Sample Program 2 Output Listing 


O 
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Module Size Processor 
modb ... 387 9080 


sexews PUBLIC DEFINITIONS *¥*%¥¥ 
modb_nine 
modb_ten 


seseee EXTERNAL REFERENCES **#**% 
modb_five 
modb_two 
modb_four 
modb_three 
modb_seven 
madb_six 
modb_eight 
modb_one 


Publfc Count = 2 
External Count = 6 


Module Size Processor 
modd .., 387 68638 


aezaee PUBLIC DEFINITIONS *##822 
modd_nine 
modd_ten 


eeeeee EXTERNAL REFERENCES *9**** 
modd_f ive 
modd_two 
modd_ four 
modd_three 
modd_seven 
modd_six 
modd_sight 
modd_one 


Warnings 
Errors 


Librasian Listings 


Figure 15-2. Librarian Sample Program 2 Output Listing (cont.) 
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= ASCII and EBCDIC Codes: 
Appendix A 


The assembler will recognize the following characters listed in Table A-1. The 
equivalent ASCH and EBCDIC codes are expressed in hexadecimal notation. 


Table A-1. ASCII and EBCDIC Codes 


Character ASCIil EBCDIC Character ASCII EBCDIC 


< 
> 
? 
@ 
A 
B 
Cc 
D 
E 
F 
G 
H 
I 
J 
K 
L 
M 
N 
oO 
P 
Q 
R 
Ss 


OO A MN PWN O™* 


| {cont.) 


Co 
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ASCil and EBCDIC Codes 


Table A-1. ASCII and EBCDIC Codes (cont.) 


Character ASCII EBCDIC 


>“ “NK MES OH 


x 


erm nheoao oR 


Character 


mT ANYE KM ade eM HOD ge Re 


ASCII EBCDIC 
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Assembler Error Messages: 
Appendix B 


Introduction 


This appendix describes the error messages and wamings that appear if errors in the 
source program are detected during the assembly process. The error message is 
printed on the listing immediately following the statement in error. 


When the assembler finds a syntax error, it does not generate code for the 
instruction or directive on the line or for any of its continuation lines where the error 
occurs. The error message is printed on the line below the error with a caret pointing 
to the offending syntax. In some cases, the assembler issues a general syntax error 
that indicates there is something wrong at the place the caret points, but the specific 
nature of the error is not determined. It then continues processing with the next 
statement. 


In the event of a syntax error, the assembler does not generate code, but it continues 
processing with the next statement. 


Most error messages are self-explanatory. The listing displays a total error count. 
The errors and messages for the assembler are listed and described in the following 
section. 


Assembler Messages and Errors 


500 


501 


502 


503 


504 


No error 

Missing argument 

The argument to a directive is missing or contains an illegal character, etc. 
Mismatch on common/noncommon section type. 

Operator expected but not found 


A symbol! was found which is invalid in this context 


Right parenthesis not valid in this context 
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505 Operator not valid in this context o) 
506 Expression terminator found prematurely 

507 Operand expected but not found 

508 Unbalanced parentheses 

509 Complex relocatable value not valid In this context 

510 Stack underflow (internal error) 

511 Invalid operands for \ operator 

512 Invalid operands for & operator 

513 invalid operands for | operator 

514 Invalid operands for || operator C) 
515 Invalid operands for = operator 

516 Invalid operands for <> operator 

517 Invalid operands for >= operator 

§18 Invalid operands for > operator 

519 Invalid operands for < operator 

520 Invalid operands for <= operator 

521 Invalid operands for >> operator 


522 Invalid operands for << operator 
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an 


s 523 Invalid operands for ° operator 
524 Invalid operands for / operator 


525 = Invalid character 


This message occurs as a result of syntactic errors. For example, a character may be 
invalid within the context where it occurs; an input line may be too long; or a 
register name may occur where it is illegal. 


526 Closing string delimiter missing 

527 = String longer than 4 characters Invaltd In this context 
528 Invalid opcode 

529 = Invalid opcode/qualifier combination 


a 530 Undefined symbol 


“ There is a symbolic name in the operand field that has never been defined. The 
symbol should have been previously defined for certain directives and was not, but 
it may have been defined after the directive. A symbol declared on the XDEF 
directive was not used in the program. 


531 invalid nesting of JF...ENDC 


532 Invalid nesting of IF...ELSEC...ENDC 


The opcode mnemonic is not a valid instruction, directive, or macro call. A macro 
defined within another macro, or conditional assembly statements is nested too 
deeply. ELSEC, ENDC, or ENDM has been used without a preceding IF or 
MACRO. 


§33 Missing ENDC 
534 {F stack overflow; limit Is 16 nesting levels 


535 This directive not permitted in absolute assembly 
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B4 


536 


537 


538 


539 


540 


541 


Code generation not permitted in OFFSET section 
Integer value is outside of its legal range 

Label! required on this directive 

Duplicate IDNT directive (ignored) 


Retocatable expression invalid in this context 


One of the following errors may cause generation of this message: a relocatabie 
expression is used for a field that is not 16 or 32 bits long; an operand that should 
be absolute is relocatable; or an ORG directive makes a reference to an external 
symbol. 


Comma expected but not found 

Invalid section name 

Section cannot be both COMMON and non-COMMON 
Nested macro definition 

Too many sections 

Invalid symbol 

This sort of symbol cannot be made an external definition 
Invalid external symbol 

Value will be sign-extended to 32 bits at runtime 

Unable to open Include file 


Invalid formal parameter name 


Microtec Research, Inc. 


&. 


a 


Assembier Error Messages Assembler Messages and Errors 

552 Invalid local symbol name 

553 Duplicate label (ignored) 
The label in the statement has previously appeared in the label field. A label on a 
SET directive previously appeared in a statement other than a SET directive, or a 
label on a statement other than a SET directive now appears on a SET directive. A 
label appears more than once in an XREF directive. A symbol defined in an XREF 
directive appears in the label field of some statement. A keyword appears in the 
label field or in an XDEF or XREF directive. 

554 Incompatible usage: Motorola does not permit a label on this directive 

555 Section was declared both Short and non-Short. Section wilf be Short 

556 NO not permitted on this flag 

557 Unknown or missing option flag 

558 Register list invalid in this context 

§59 .Wor.L extension on register not valid in this context 
You should verify the validity of the extension on the register. 

560 Aregister in a colon-separated pair is Invalid tn thls context 
Register pairs cannot be separated by a colon in this instruction. 

561 Acolon-separated pair of registers is invalid in this context 
Register pairs cannot be separated by a colon in this instruction. 

562 Register expected but not found 

563 Aregister in a register tist Is invalid in this context 

564 Registers separated by - in register list must be in ascending order 
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B+ 


565 


566 


567 


568 


569 


570 


571 


572 


573 


574 


575 


576 


577 


578 


579 


580 


Registers separated by - in register list must be of same type ks 
Invatid expression containing a register 

Left parenthesis expected but not found 

Square brackets Invalid in this context 

Multiple arithmetic expressions invalid within an operand 

Left brace expected but not found 

Colon expected but not found 

Right brace expected but not found 

Equals sign expected but not found 

TO or DOWNTO expected but not found () 
DO expected but not found 

Nesting of WHILE...ENDW invalid 

Nesting of REPEAT...UNTIL invalid 


Nesting of IF...ELSE...ENDI Invalid 


Invalid extension for nested INCLUDE directives. ELSE and/or ENDI have been 
used without the preceding required structural syntax directive. 


Nesting of IF...END! invatid 


Nesting of FOR...ENDF invalid 


Invalid extension for nested INCLUDE directives. ENDF has been used without 
the preceding required structural syntax directive. 


UO 
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581 


582 


583 


584 


585 


§91 


592 


593 


594 


595 


BREAK found outside a structured-syntax loop construct 
NEXT found outside a structured-syntax loop construct 
Invalid condition code in structured syntax directive 


< (condition code) expected but not found 


Condition code required for this instruction. 


Code generated Is unequivatent in some cases. Recoding 
recommended 


THEN expected but not found 
This instruction has too many operands 
This combination of operands is not valid for this instruction 


Too few bytes allocated on Pass 1 for forward reference 


This instruction will not work on the declared processor type 


The instruction or operand is illegal for the specified processor. Use the CHIP 
directive to specify another processor. 


FAIL directive assembled 
A generated program error has occurred. 


Register list required for REG directive operand 
This directive invalid outside a macro 
This character invalid within real constant 


A real constant was expected here 
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602 


603 


604 


605 


606 


607 


608 


Real numbers invalid in this context 
This real number is too small to represent. Zero substituted 
This real number is too large to represent. Infinity substituted 


Macros nested too deeply. Use OPT NEST if this was your Intent 


When nesting macros, the buffer available for macro parameters is full. 
Real numbers invalid in this context 


Value was truncated to fit in its field 


An evaluated expression or constant is out of range for the field of the processor 
instruction. 


Calculated displacement does not fit in its field - truncated 
Structured Directives not properly closed ~ 


Maximum number of typed sections exceeded In HP mode 

When assembling with the -h option, more than one relocatable section was mapped 
to HP section PROG, to HP section DATA, or to HP section COMN. Local 
symbols from these extra sections are not written to the asmb_sym file and will be 


unavailable for debugging. To eliminate this warning, move the extra sections into 
a new source module. 


Out of virtual memory 
Invalid Value for alignment, can only be 0, 1, 2 or 4 
End of File inside a macro or repeat definition 


Expression stack overflow 


Expressions are stored in a stack to facilitate evaluation. The stack can be exceeded 
by a very long expression. 
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610 
611 
612 
613 
614 
615 


621 


623 


624 


625 


626 


Illegal branch to odd address 

Unable to create or open an intermediate file 

Iilegal high level debug syntax 

Incompatible processor/co-processor combination 
User label conflicts with register name 

Floating point hex number too big for specified size 


Macro/repeat definition terminated by assembler. 

An ENDR (end of repeat) and ENDM (end of macro) is provided by the assembter 
in order to terminate an incomplete macro/repeat definition. This is a warning. 
Too many forma! parameters. Limit Is 36 

You have too many formal parameters in a macro definition. Fix the error by 
reducing the number of formal parameters. 

Macro names cannot contain a period (.) 


A period can only appear as the first character of a macro name. Other than this 
exception, it will be considered as part of a qualifier (.B, .W, -L, or .S) when the 
macro is called, 


Macro definition has too many local symbols 


You have too many local symbols in a macro definition. The maximum number of 
local symbols allowed in a macro definition is 90. Reduce the number of local 
symbols in your macro definition. 


invalid model parameter 


The model parameter may be missing in the IRP assembier directive. This is an 
error. 
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630 
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632 


633 
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Expanded macro line is too long ) 


The line in the macro definition is too long for the macro preprocessor’s internal 
buffer. This is an error. You should break the line into two shorter ones, and 


reassemble. 


egal CHIP identifier 
Self explanatory. 


Invalid operand for .STARTOF. operator 
A section name is expected as an operand. 


Invalid operand for .SIZEOF. operator 
A section name is expected as an operand. 


The number ot nesting levels for macros cannot exceed the maximum 


The maximum nesting level is 8 (PC hosts) or 100 (non-PC hosts). 


.W or .L extension on cache not valid in this context YY 


The extension is not allowed on cache registers. 


Extra operand(s) ignored 
Extra operands were encountered on the remaining source lines and were ignored. 
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Introduction 


This appendix describes the error messages and warnings that can appear during 
linking. Errors and messages are listed beneath the actual command in error. For 
most load errors, the message is followed by the record number in the input module 
and the actual record in error. For a particular module, the module name is also 
listed at the start of the messages. 


Load messages normally occur during the loading of object modules initiated by the 
LOAD command. Errors and messages from the linker will be non-fatal or fatal. If 
the error is non-fatal, the load will proceed after the etor is reported. If the error is 
fatal, the linker will report the error, and the load will terminate immediately. 


Most load errors should not occur. If they do, first reassemble the program and then 
reload. If the error persists, contact Microtec Research, Technical Support. 


| Message Severity Levels 


There are two classes of errors that can occur during linker program execution. The 
first class is non-fatal and processing proceeds after the error is reported. The 
second class is fatal and processing is abandoned. 


Status messages can be one of the four types listed in Table C-1. 


Table C-1. Linker Message Severity Levels 


Not fatal. 


Informative and often appears in conjunction with 
another error message. 


Usually fatal, but processing continues to facilitate 
further error checking. 
Always fatal. Processing aborts. 
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301 


302 


303 


304 


305 


306 


307 


Bad IEEE Object Record 

Either the object module has been corrupted or it is not a Microtec Research 
IEEE-695 relocatable object file. 

Maximum Number Of Sections Exceeded 

The maximum number of allowable segments (64) has been exceeded. 


Section Mismatch 

A section was typed common in one place and noncommon in another, or short in 
one place and long in another. This message may arise if a section is mentioned for 
the first time ina SECT, COMMON, PAGE, CPAGE, or NOPAGE command, 
as these commands assign the long attribute to newly found sections. 

Section Overlap 

Due to addresses that you have specified or absolute sections, one or more of the 
sections overlap. This is an informative message and loading continues. 

Module Too Large 

At final load time, the combined lengths of all program sections exceed the 
maximum memory size established by the CHIP command. 

Reserved Memory Table Full 

The linker has run out of memory in the host system. 


Out of memory 
The linker has run out of memory in the host system. 


Duplicate Public 


A PUBLIC is defined that was already defined in another module. Loading will 
continue and the symbol will be listed. 
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311 


312 


313 


314 


315 


316 


Invalid CHIP Command 
The CHIP command you specified is not a legal linker command. 


Invalid Command 


You have specified a linker command that is not legal. 


Load Completed 


Message indicates normal load. 


Load Not Completed 
Message indicates abnormal load. 


Invalid ORDER command 

You have specified an ORDER command in such a way that it is not a Jegal linker 
command. Check the syntax for this command in the Microtec Research ASM68K 
Reference Manual. 

invalid Operand 

An operand specified for a command contains invalid characters, does not exist, or 
is too large. 

Chip Inconsistency 


The linker has encountered a file assembled with a CHIP directive which has 
greater capabilities than the CHIP specified to the linker. For example, a file 
assembled with the CHIP 68020 directive is loaded with the CHIP 68000 link 
command in effect. The module may contain instructions which cannot execute on 
the target chip. 

Maximum memory exceeded 


The program exceeds the memory available for the target microprocessor. 


Short memory exceeded 
The short memory specified is not enough for all short sections. 
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318 


319 


320 


322 


323 


Section Assigned address below BASE 


An absolute or relocatable section has been assigned an address less than the 
address specified in the BASE command. 


internal Error 


The linker has encountered a fatal internal error. A seek error can be caused by a 
device that is full. 


Cannot Open File 
The linker is unable to open the relocatable object file. 


UNRESOLVED EXTERNALS 
The unresolved external symbols are listed following this error message. 


8-bit Value Out of Range 


A relocated 8-bit value is out of range. An 8-bit field, generally an immediate value, 
has too large a value. Loading continues, but the loaded program often will not run. 
You should investigate. 


All values are evaluated as unsigned 32-bit values. These values are expected to be 
within 8 bits sign-extended (i.ec., $FFFFFF80 to $FFFFFFFF or 0 to $7F) 
displacements that will be sign-extended to 32 bits at run-time (e.g., the operand of 
MOVEQ). In the more common case of immediate values which are not sign- 
extended at run-time, the expected range is 0 to $FF or $FFFFFF00 to $FFFFFFFF. 


In either case, the value inserted in the object module is the low 8 bits of the 
complete 32-bit value, whether this error is reported or not. This message interrupts 
the link map when it appears. The section and location relative to the beginning of 
the subsection (j.e., the address that appears on the assembler listing) are given for 
each occurrence, The module is shown in the preceding line of the link map. 


16-bit Value Out of Range at nnnn in module xxxx section yyyy 


The relocated value of an expression will not fit into a 16-bit field. Loading 
continues, but the program may not run properly. The location nnn indicates the 
offset within section yyyy of module xxx. You should investigate. 


For example, an absolute short instruction refers to a location that is not in the range 
$0 through $7FFF or $FFFF8000 through $FFFFFFFF. A PC-plus-16-bit- 
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326 


327 


328 


O 


displacement instruction may refer to a location that is more than +/- 32K bytes 
from the present location. 


Often this error occurs in conjunction with an Unresolved External error. The 
linker assigns the value zero to undefined symbols and then tries to reference 
address 0. 


All expressions are evaluated as unsigned 32-bit values. If a 16-bit field will be 
sign-extended at run-time, then the value must fall within the range $0 through $7/ 
FFF or $FFFF8000 through $FFFFFFFF, If the field will not be sign-extended, the 
value must fall in the range $0 through $FFFF or $FFFF0000 through $FFFFFFFF. 


In any case, the value inserted into the field is the low 16 bits of the value. 


Section Mismatch Between Symbol Deft and Ref for Symbol 


An XREF from the assembler had a section associated with it which does not match 
the section of the XDEF with the same name, or does not match the section 
associated with a previous XREF to the same symbol. Unspecified sections are 
considered to match any section name. The symbol is treated as undefined. 


This message may occur in the case of duplicate XDEFs as well. 


Illegal HP section name 


The HP object file contains an illegal section name. 


Cannot open temporary file 

The CONFIG.SYS file may not have had enough files and buffers. For more 
information, refer to the Microtec Research ASMO68K Installation Guide. 

Iilegal ALIAS command 


IIlegal command for an ALIAS section 


A section that was aliased via ALIAS to another section was mentioned in a linker 
command, The original section name should not be referenced. 
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334 
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336 


337 


Multiple initialization of a COMMON section 


This error occurs when more than one file defines data or instructions (as opposed 
to just reserving space) in the same COMMON section. Since each file’s 
contribution toa COMMON section overlap, data from one file may overwrite data 
from a second file. 


Iliegal ALIAS for a COMMON section 


Inconsistent EEE object format 


The linker has encountered a relocatable module that it cannot properly interpret. 
Usually, this results from using different versions of assembler and linker programs. 
A later version of the assembler will produce a relocatable object module that is 
fejected by an earlier version of the linker. 

Object contains errors 

The assembler detected errors when the relocatable object was produced, Check the 
source code for instructions that will not execute properly. 

Source file does not exist 


This message is for debugging purposes. The debugger normally issues an 
informative message containing the location of the source file. If the source was 
compiled and assembled and then the source file was deleted, the linker issues this 
informative message. 


Local symbols in CODE section 
Local symbols in DATA section 
Loca! symbols in COMN section 


filegal command for incremental linking 


The command file can contain only LOAD statements when incremental linking is 
used. Any other statements in the command file will generate this error. 
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Duplicate ROM section 
Duplicate INITDATA message used in older versions of the linker. 


Section moved to high short section 


As the linker was locating short sections in low base page ($0000 through 7FFF), it 
encountered a short section which would not fit in low base page. It located the 
section in high base. High base page depends on the CHIP command, as follows: 


68008 $000F8000 through $000FFFFF 

68000/10 $O0FF8000 through $O0FFFFFF 

68020/30/40 $FFFF8000 through $FFFFFFFF 
Out of virtual memory 


Self-explanatory. 


This command is Illegal after LOAD is used 


Self-explanatory. 


Incompatible incrementally linked object. Recreate the object 


The object file was incrementally linked by a Version 6.4b or earlier version of the 
linker. This object file is not compatible with Microtec Research’s latest version of 
the linker, Relink using the latest version of Microtec Research’s linker. 


Duplicate Public From Library Module -- ignored 


The public symbol that caused this message to appear was already defined in the 
library. Loading will continue, and the symbol will be listed on the link map, This 
message is a warning. 


Could Not Construct Full Path Name 


You may have tried to link objects that were created on a different host. Recreate 
the objects on the same host and then relink. This message indicates a non-fatal 
error. 
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Command Ignored: 

This warning message usually appears with a companion message that gives the 
reason for why the command was ignored. 

Module Not Found. 

Self-explanatory. This message indicates a non-fatal error. 


Section Previously Specified or Non-existent 

A section or subsection specified by the MERGE command is either non-existent 
or already merged. This message is a warning. 

Illegal Multiple Case Specification for class 


Each class (PUBLICS, MODULES, SECTIONS) can have only one case 
specification (CASE, UPPERCASE, or LOWERCASE). If more than one case 
specification is used for class, this error message is generated. This message 
indicates a non-fatal error. 


Write error - disk may be full. 
Self-explanatory. 


Section Mismatch Between PUBLIC Def and Module Ref for Symbo! 


A section mismatch has occurred for a symbol that was defined by a PUBLIC 
command and referenced in some module by an XREF assembler directive. This 
message is a warning. 


Redefinition of symbol_name 


A symbol_name defined by the PUBLIC command or a register has been redefined. 
A register can be (re)defined using the INDEX command. A public symbol can be 
(re)defined using the PUBLIC linker command or the XDEF assembler directive. 
The value of the symbol specified by the last PUBLIC command will override the 
previous value. This message is a warning. 


Too Many Errors 


Too many exrors have been found. Any additional errors found after this message 
is shown will not be reported. 
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Cannot ABSOLUTE unknown section, section 
The section is not defined in any of the modules loaded by the linker. 


Cannot ALIGN unknown section, section 
The section is not defined in any of the modules loaded by the linker. 


Cannot ALIGN absolute section, section 


Absolute sections have a fixed starting address and cannot be aligned. 


Absolute section cannot have the same name as other sections, 
section 


Sections with a defined location address cannot be combined with a relocatable 
section, This error message appears when an absolute section has the same name as 
arelocatable section. 


Combined section exceeds memory space, section 


The combined section has a size greater than the processor memory space. The 
program ’s code or data is too large as a result. 


Section size shrunk for section 


The default size of a section is greater than the size specified by the SECTSIZE 
command. Only sections that are of type common can be shrunk. 


24-bit Value Out of Range at address In module section section 


The relocated value of an expression will not fit into a 24-bit field. The address 
address indicates the offset within the named section of the named module. Loading 
continues, but the program may not run properly; you should investigate. 


All expressions are evaluated as unsigned 32-bit values. These values are expected 
to be within 24 bits sign-extended (i.e., $FF800000 to $FFFFFFFF or 0 to 
$7FFFFF) displacements that will be sign-extended to 32 bits at runtime. In the 
more common case of immediate values which are not sign-extended at runtime, the 
expected range is 0 to $FFFFFF. 


In either case, the value inserted in the object module is the low 24 bits of the 
complete 32-bit value. This message interrupts the link map when it appears. The 
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374 


375 


376 


377 


379 


380 


section and location relative to the beginning of the subsection (i.e., the address that 
appears on the assembler listing) are given for each occurrence. The module is 
shown in the preceding line of the map file. 


ORDER command could not be obeyed for section, section 


The linker is unable to allocate memory in the order specified for the section listed 
in the ORDER command. A possible example is: 


ORDER sect1, sect2, sect3 
SECT sect2=0 


Since sect2 must begin at address 0 there is no way sect 1 can precede it. 


No modules were loaded 
No LOAD or LOAD_SYMBOLS commands were specified. 


The linker assumes that something is wrong if no modules were actually loaded. 
There may be a syntax error preventing the LOAD command from being read, such 
as the END command inserted before any LOAD commands. If the only LOAD 
argument is a library file, the linker will load modules from a library only if they 
resolve undefined externals. If there are no undefined externals, the linker will not 
LOAD the library. 


Invalid modifler, modifier 


’ The linker command does not support this modifier. This message is a warning. For 


legal modifiers, refer to the Linker Commands chapter in this manual. 


Duplicate section name specified in INITDATA command(s) 

The INITDATA command contains duplicate section names. This message is a 
warning. 

Invalid INITDATA command 

Missing operands in the INITDATA command. 


* is no longer a valid comment character in this context 
The asterisk (*) character denotes the beginning of a comment line only if it starts 


in the first column. Use the semicolon (;) character for comments that do not begin 
in the first column. 
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This appendix contains librarian error messages. 


Message Severity Levels 


There are two classes of errors that can occur during program execution of the 
Microtec Research LIB68K Librarian. The first class is non-fatal and processing 
ca a ea ela cae 
abandoned. 


Status messages are shown in Table D-1. 


Table D-1. Librarlan Message Severity Levels 


Warnings Not fatal. 
Messages Informative and often appear in conjunction with 


another error message. 

Errors Usually fatal, but processing continues to facilitate 
further error checking. 

Fatal Always fatal, Processing aborts. 
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Could not close file filename to open another file. 


In order to reduce processing overhead, the librarian keeps file open with the OPEN 
command. This message is displayed if too many files are open and the librarian 
unsuccessfully attempts to close a file in order to open a new one. To remedy this 
situation, reduce the number of files you are working with during a given session. 


Unable to open file filename. 


The librarian could not open the named file when executing an ADDMOD, 
REPLACE, or OPEN command. This error could be caused by either an inyalid 
file name specification or when the specified file does not exist.'The librarian 
ignores the command that generates this error. 
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106 


Unable to close file filename. 


‘The librarian generates this error when it encounters an operating system error and 
cannot close the named file. This message typically is accompanied by another error 
message that provides a more specific reason for not closing the named file. 


File filename not included. 


The librarian issues this message when it cannot execute the ADDMOD command 


- because the named file is corrupted or does not exist. This message has a companion 


message that specifically states why the named file is not included in the library. 


File fibrary_name exists already. 


The librarian generates this message when you use the CREATE command and the 
named library currently exists. The librarian displays a warning in batch and 
interactive modes. 


107 File filename does not exist. 


108 


109 


120 


201 


The librarian generates this message when you issue an OPEN command and the 
named file does not exist. 

Library file fibrary_name not opened. 

This message has a companion message that specifically states why the library file 
was not opened. 

Library file /ibrary_name not opened. 

This message has a companion message that specifically states why the library file 
was not opened. 

Use HELP for proper command syntax. 


Self-explanatory. 


Module moduie_name not found. 


The librarian could not locate the named module in the library to execute a 
DELETE, REPLACE, or EXTRACT command. 
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Module module_name already exists in current library. 


The librarian cannot execute an ADDMOD or ADDLIB command because the 
module named in the message exists in the current library. If you wish to replace a 
module in the library, use the REPLACE command. The librarian ignores the 
ADDMOD or ADDLIB command that contains a duplicate module name. 


filename is a library file. 


The librarian generates this error message when it attempts to execute an 
ADDMOD or OPEN command, and the associated file name is not an object 
module. The command containing the erroneous file is ignored. 


filename is not a library file. 


The librarian issues this command when it attempts to execute an ADDLIB or 
OPEN command, and the associated file name is an object module. The librarian 
ignores the command containing the erroneous file. 


Module module_name is not included in the library. 


The librarian issues this message with a companion message that gives the specific 
reason for not including the named module in the library. This messages describes 
the result: the named module is not included in the library. 


Bad object record. 


Either the object module has been corrupted or it is not a legal relocatable object 
file. The librarian issues this message with a companion message, which names the 
file with the bad object record. Whatever command is associated with the bad object 
record file will be ignored. 


Bad library header record. 


The library has a bad header record. The librarian issues this message with a 
companion message which names the file with the bad header record. The 
command associated with the bad library header record will be ignored. 
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250 
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253 


254 


Duplicate symbol symbo/_name. 


A module named in an ADDLIB, ADDMOD, or REPLACE command has the 
same public definition symbol that occurs in another module. The librarian issues 
this message with a companion message that provides information about what 
action it takes. 


The librarian considers symbols to be case-sensitive. 


Bad object record In file filename. 


The named library or module file may have been corrupted. 


Out of memory. 


The librarian issues this message when it encounters insufficient system memory to 
execute commands issued since the last CREATE or OPEN command. 


Failed writing library. Reason. 


The librarian generates this message when it attempts to execute a SAVE 
command, and cannot. The message provides the reason for the inability to create a 
library. The librarian abandons the current session affected by the SAVE command 
that caused the error. 


Library /ibrary_name not written. 


The librarian issues this message when an error occurs earlier in the session that 
prevents the library from being saved. This message is typically accompanied by 
another message that contains the reason the named library was not created. 


Failed writing module module_name te file filename. 


When attempting to execute an EXTRACT command, the librarian cannot write 
the named module from an existing library to the new file which is external to the 
library. A companion error message describes the reason that the module cannot be 
extracted. If an error is encountered in batch mode, all commands following the 
EXTRACT command will not be executed; however, they will still be checked for 
syntactical validity. 


Microtec Research, Inc. 


Librarian Error Messages Librarian Error Messages 
te SD ye oe TS 8 
255 Replacement not done. 


The librarian issues this message when it cannot execute the REPLACE command 
for the reason specified in the companion message. 


256 Extraction falled. 
The module named in the EXTRACT command is not extracted. 


257 Syntax error In command. 


The librarian generates this message when it encounters an incorrect command 
sequence or an incorrect command syntax. 
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Absolute Section 


Address Expression 
Base Address 


Common Section 


Load Address 


Module 


Noncommon Section 


Numeric Expression 


Register Expression 
Relocatable Section 


Short Section 
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Part of assembly program that is to be loaded at fixed 
locations in memory. It contains no relocatable 
information. 

An expression whose value represents a location in 
memory. 

Lowest address considered for loading relocatable 
sections of the absolute object module. 


Section attribute. This type of section contains 
variables that can be referenced by each module. All 
common subsections are loaded beginning at the same 
address. 


Memory address where the lowest byte of a section is 
placed. 


A module is the relocatable object code resulting from 
a Single assembly. It can contain pieces of one or more 
sections. 

The linker combines pieces of a section from different 
modules. Such pieces always make up a contiguous 
block of memory, assuming they can be combined at 
all. 


Section attribute. This type of section contains code 
only, All subsections of a noncommon section are 
loaded into a contiguous block of memory and do not 
overlap. 

An expression whose value represents a number, 


An address expression whose base or index attribute is 
non-null. 


General purpose section which can contain both 
instructions and/or data. 

Section attribute. This type of section can be 
referenced by absolute short addressing mode. 


Glossary 
ee 


Starting Address Location where execution begins. 


Subsection Individual pieces of code from various modules which 
make up 4 section. 


VU 
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This appendix discusses modifications made to the ASM68K Assembler, LNK68K 
Linker, and LIB68K Librarian to support C++ name mangling/demangling. 


Name Mangling/Demangling 


In the C++ language, you can use the same names to refer to different operations; 
this practice is known as ‘‘overloading’’. Since the same name is used, C++ 
introduced a unique naming encoding scheme to differentiate between two names 
used for the different operations. Therefore, you can name one function 
closeout (char *name, float balance) to indicate closing out a bank account, 
and pass it a parameter indicating the customer’s name and return a parameter 
indicating the closing balance. You can name another function in your program 
closeout (char *telex, int *account) indicating a bank branch to notify about 
the customer’s closed account. Although both these functions have the same name 
(closeout), C++ uniquely identifies each function based on the parameters passed 
by encoding this information into a ‘‘mangled’’ name. 


ASM68K Assembler 


A sample C++ file, simplel.cc, was compiled on a UNIX operating system. The 
resulting simple1.o object file was linked with the map option set, so that a link map 
was generated. Figure F-1 shows the sample C++ source file. Figure F-2 shows the 
assembler input file, and Figure F-3 shows the assembler output file. 


#include "stream.h" 


void main() { 


cout << "hello"; 


} 


Figure F-1. C++ Program Listing 
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Use the OPT CRE or OPT X directive in your assembler source file to demangle 
all labels that fit the C++ name encoding scheme in your cross-reference and 
symbol tables. 


Assembler Input File 


Figure F-2 shows a sample ASM68K input file (extension .8) which uses the OPT 
CRE assembler command. 


Microtec(R) Research Inc. 88K C Compiler 4.1 

Host Operating System ~ SUN3 UNIX 

Command Line Options Specified: 
-Ri/tmp/hello.i /tmp/hel lo.» 


TTL /tmp/hello.*x 
MCCBBK 4,1 S3@88398 830426c 
OPT CRE ,NOABSPCADD, E , CASE 
NAME hello 
SECTION zerovars, ,D 
_-Sé_lostream init DS.B 2 
XREF -cout 
XCOM _openprot__?7f1lebuf ,4 
XCOM _initcount__idlostream_init,4 
XCOM _stdstatus__13Iastream_init,4 
XCOM _stdioflush_dios,4 
XCGM _nextword__3ios,4 
XCOM _nextbit__31os,4 
XCOM _floatfield _dios,4 
XCOM _adjustfield__Jios,4 
XCDOM _basefield__3ios,4 
SECTION code, ,C 
XREF _do_opfx__7ostreamFyv 
XREF _do_osfx__7ostreamFy 
XREF ~~ 1s__7ostreamFPCc 
XREF exit 
XREF —__ct__i3lostream_initFy 
XREF —_dt__i3lostream_initFv 
_put__7ostreamFc: 
movem.1 a2/d2,-(sp) 
move.) 16(ep),d2 
movea.1 12(sp),82 
movea. } 4(a2),28 
tst.1 28(aB) 
beq-s L26@8i 
move.1] a2,-(sp) 
jsr -do_opfx_7ostreamFy 
addq.1 #4,sp 
bra.s L20082 
120881: 
moveq #1,d8 
L28882: 
tst.1 d@ 
beg.1 Li 
movea.1 4(a2),a8 


Figure F-2. ASM68K Input File 
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ee 
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1 a a I 


L26BB3: 


Microtec Research, Inc. 


movea. 1} 
move, 1 
movea. i 
movea.1 
cmp.1 
bcs.s 
move.b 
ext.u 
and1.1 
move.1 
movea.] 
movea.] 
movea. 1 
move.w 
ext.1 


movea.1 
add.1 
move.1 
movea.1 
movea.1 
movea. | 
movea.1 
jsr 
addq.1 
bra.s 


movea.} 
movea.1 
move.1 
addq.1 
movea.1 
move .b 
move.b 
ext.w 
and{.1 


moveq 
emp.1 
bne.s 
movea. 
ori.) 
movea, 
ori. 
movea. 
ori.] 


movea. 
tst.1 
bsq.s 
move .t 
jer 

addq.1 


move.1 
movem.1 
rts 


code: 238 bytes 


SECTION 
oC.B 
os 


8(a6},aB 
12(a@), do 
4(a2),a8 
8(a8),a@ 
16(a@), da 
L28883 


4(a2),a8 
6(aB),aB 
86(a6), 88 
16(a8),d@ 
[3] 


4(a2),aa 
8(a@),d@ 
d8,-(sp) 
4(a2),ad 
8(ad) ,a@ 
96(a@),a8 
20(a8),a8 
(a8) 
#8,8p 
L28984 


4(a2),a8 
8(a9),e8 
12(a@) da 
#1,12(a@) 


4(a2),a8 
#3,12(a8) 
4(a2),a0 
#3,16(aB) 
4(a2),a0 
#3, 16(aa) 


4(a2) ,ab 

28(aB) 

Li 

a2,-{sp) 
—do_osfx__7ostraamFy 
#4,58p 


a2,d@ 
(sp)+,a2/d2 


strings, ,R 


“tS hello, ct: ok’,18,8 


Figure F-2. ASM68K Input File (cont.) 


stack: @ bytes 
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SECTION code,,C 
XDEF main 


pea _-SL 

pea tout 

jsr ___}s__7ostreamFPCc 
eclr.] ~(sp) 

jer exit 

lea.1 12(sp),sp 

rts 

code: 32 bytes stack: 8 bytes 
XDEF —--8ti__hello_cxxmaing 


sti__hellowcxmmain_: 


pea _.56_iostream_init 
___ct__13Iestream_initFy 


: 16 bytes stack: @ bytes 
——std__he?]o_cxx_ma inl 


__std__hel lo.cxx_main_: 


; code: 296 bytes, const: 2@ bytes, bss: 2 bytes 


cir.1 (sp) 

pea _-Sé_iostream init 

jsr —-—dt__13l ostream initFy 
addg.1 #8,sp 

rts 

code: 18 bytes stack: @ bytes 
SECTION initfini,,R 

0C.L ——sti_hel lo_cxx_main_ 
DC.L ——_std_hetjo_cxxmain_ 
ENO 


Figure F-2. ASM68K Input File (cont.) 
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Assembler Listing File 


Both the mangled C++ names and the demangied C++ names (i.c., the C++ original 
source file name) will be listed for the cross-reference and symbol tables. The 
ASM68K output file is shown in Figure F-3. 


Microtec Ressarch ASM66B8B Version 6.7F Fri Aug 93 21:58:52 1998 Page 1 


Command line: ../../asm/asm68k -1 hello.s 

Line Addrass 

Micratec(R) Research Inc. 68K C Compiler 4.1 

Host Operating System - SUNS UNIX 

Command Line Options Specified: 
-Ri/tmp/nello.1 /tmp/hello.xx 


TTL /tmp/hello.xx 
MCCEBK 4.1 §$3@88388 s838426c 
OPT X, NOABSPCADD, E , CASE 
NAME hello 
SECTION zerovars,,D 
gagaaaea _,-S8_iostream_init oS.8 2 
XREF —cout 
XCOM _openprot__7f{lebuf ,4 
XCOM _initcount__19lostream_init,4 
XCOM _stdstatus__13lostream_init,4 
XCOM _etdioflush__3ios,4 
XCOM _nextword__3ios,4 
XCOM _nextbit..3108,4 
XCOM _floatfield__3ios,4 
XCOM _adjustfieltd_3ios,4 
XCOM _basefield__3ios,4 
SECTION code, ,C 
XREF ~do_opfx__7ostreanFy 
XREF _do_osfx__7ostraamFy 
XREF ___. 1s__7ostreamFPCc 
REF aoxit 
XREF —_ct__13lostraam_initFy 
XREF —.dt_ 13 astraam_initry 
~put_7ostreamFc: 
gaee8Bee 48E7 movem.1] a2/d2,-(sp) 
e9aaaaB4 242F move.1 16(sp),d2 
‘Q88880B8 246F movea.1 12(sp),a2 
@gegaaec 205A movea.1 4(a2),08 
6¢088016 4AA8 tst.1  28(a@) 
eab88014 678C beq.e L20@01 
ggeeeeis 2FBA move.? a2,-(ep) 
69888818 4EB9 jsr _do_opfx__7ostreamFv 
6aeees1E S8aF addg.1 #4,sp 
eg880828 6882 bra.s 120882 
L26881: 
8008822 7801 moveq 
L20902: 
@B8888824 4AG8 tst.1 
eoee8826 6780 beq.1 
@g8e8024 286A movea.) 4(a2),a8 
@8e88a2E 2868 movea.1 6(a8),a8 
ageaees2 2028 move.) 12(a0$,d0 
88088036 286A moves.) 4(a2),a@ 
@288883A 2868 moves.) 8(a8),a@ 
@BegeBSE BAAR onp.1 16(e8) ,dB 


eee OOH oh i he 
nN ao 


Figure F-3. ASM68K Output File 
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Microtec Research ASMG68280 

/tmp/hallo.xx 

Line Address 

S51 e@Bnae42 BSE 

52 9@paae44 1802 

53 980868046 4862 
aeeeee4a 6288 A888 BFF 
BBGBBR4E 2FeB 
@8@B8858 266A 8OB4 
oan88854 2868 6880 
eagaeess 24068 8824 
@aBeeest 3628 e818 
gagsesse 48ta 
BBOBGRE2 286A BBB4 
BB98BBB66 DBAS aaeB 
BBGBOBEA 2F0B 
eBaage6C 286A A884 
88898878 2068 8808 
@9888874 2668 6624 
8888078 2068 8014 
@aeaee7C 4E98 
6o@8887E SOBF 
eageease GeiE 


@geeees2 2G5A 
G@BBBRB86 2868 
@geageB8A 2828 
@9Q88GBE S2A8 
99288892 2848 
eeBgeas4 1882 
oBBBeass 1888 
Bpeeeass 4682 
@BeaBe9A 8288 8808 


@BB8G8A8 72FF 
88888042 B2B8 
@BBB88A4 6624 
B@BGBBBAG 206A B8B4 
Q9gaeaAd edAs GEAa 
eeec 
@BAGEBB2 286A 8284 
8BGGeBR6 eas Bae 
0618 
BBEBOBBE 246A BBE 
BBaGBeC2 BAB A808 
8618 


@BBBABCA 2A6A 2884 
@BBBSECE 44A8 BB1C 
eBeeasb2 678A 

@88888D4 2FGA 

@80888D6 4£B9 gae8 anbea E 
@aea8eDC S8BF 


Figure F-3. ASM68K Output Fite (cont.) 
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L28083: 


Li; 


bes.e £26883 
move.b 

ext Ww 

andi.) 

mova.1 

movea.] 4(a2),a8 
movea.? &(a@),a@ 
movea.1 36(a@),aa 
move.w 16(af),d@ 
ext.t dB 
movea.1 4(a2),a8 
add.1 6{a8),de@ 
move.] @8,-(sp) 
movea.1 4(a2),9@ 
movea.1 6(28),a@ 
movea.1] 36(a8) ,aB 
movea.] 20(a8),a8 
jsr (a@) 
addq.1 #6,6p 
bra.s L26004 


movea.1 4(a2),a8 
movea.] 8(e@),a@ 
move.) 12(a@),d8 
addq.1 #1,12(08) 
movea.? d@,a@ 
move.b 2,08 
move.b 0, (af) 
ext.w da 

andi.1 #255,d0 


moveq = #-1,d1 
emp.1  d@,d1 
bne.s 12 
movea.1 4(a2),a8 
ori.) #3,12(a8) 


movea.1 4(a2),a8 
ori.] #9,16(28) 


moves.1 4(a2),a8 
ori.1 #4,16(a@) 


movea.] 4(a2),a@ 
tst.t  26(a@) 
beq.s Li 
move.1 a2,-(sp) 


Fri Aug 3 21:58:52 1998 
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jsr -do_osfx_7ostreamFy 


addq.1 #4,sp 


Microtec Research, Inc. 


UO 


we 


il 
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/tmp/hel lo. xx 
Line Address 


99 

| 109 
104 
102 
103 
104 


Microtec Research, Inc. 


QBGBBADE 208A 
6GQB8BER 4CDF 
@BAG8GE4 4£75 


@@@B8888 2121 
§ 


2668 6S6C 


CBF 2026 632B 


283A 
. 38 
8898914 


BBB0BBEG 4879 
aBeaageC 4879 
G@BBEBF2 4EB9 
@BBGGBFS 42A7 
OBaBBBFA SEBS 
8868188 4FEF 
66688184 4E75 


8880186 4979 
ee88818C 4EB9 
68688112 Seer 
@6880114 4E75 


88688116 4247 
@66ad116 4679 
69ee811E 4E69 
68886124 SBBF 
08880126 4675 


eeeseeee eaaa 
eaave8e4 aAea 


266F 6BBA 


9ee8 8a88 
Beee BGRG 
B88 Baa 


aoe gaaa 
aac 


Bee 8aeB 
8688 9888 


eeas aaae 
aaaB 8b00 


Version 6.7F 
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move.1 a2,c8 
movem.1 (sp)+,a2/d2 
rts 

code: 238 bytes 
SECTION strings, ,R 
pc.8 *tt hello, ct#: ok’,18,8 


stack: @ bytes 


os @ 
SECTION code, ,C 
XDEF —main 


pes =-Sl 

pea _cout 

jer ~— 1s... 708streamFPCc 
clr.1 (sp) 

jer noxit 

lea.l 12(sp),sp 

rts 

code: 32 bytes stack: @ bytes 
XDEF __sti__hel jo_cxx maine 


—__st4__hel lo.cxx_main_: 


_- S8_tostream_ init 
—ct__13lostream inttFy 


code: 16 bytes stack: @ bytes 
XOEF _--std_hello_cxx_main_ 


___std__hel lo_exx main: 


cir.l ~(sp) 
pea _-88_tostraam init 
jer _--Ut__13Iostream_initFy 
addg.1 #68,sp 
rts 

code: 18 bytes stack: @ bytes 
SECTION initfini,,® 
oc.t ——sti__hel lo_exx_maine 
oc. ——std__hello_cxx main 
END 


Figure F-3. ASM68K Output File (cont.) 
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/tmp/hel lo. xx 
Cross Referance 
Value References 
code :@@8808DE 44 34 -98 
code :B848BBCA -31 
code : 80888822 -48 
coda : 88898824 A2 
code : 68998862 “71 
code :BBABBBAB -B1 
_-S8_iostream init zerovars : 80040968 -11 119 12 
--St strings :88808080 -164 189 
a ct__13Tostream_initFy 
Iostream_init: :Iostream_init() 
External} 27> «128 
__dt__13I ostream initFy 
Iostream_init: :~Iostream_init() 
External 26 128 
___1s__7ostreamFPCc 
ostream: :operator<<(const char*) 
External 25 111 
_—std_hello.cxxmain. code 709088116 -124 «-125 
___sti__hello_cxx_main_ code 300600186 -117 -118 
_adjustfisld_3ios 
jos: :adjustfistd 
External -28 
_bassfield__Sios 
jos: :hasefisld 
External 
cout External 
-do_opfx__7ostreamFy 
astraam: :do_opfx() 
External 
_do_osfx__7ostreamFy 
ostream: :do_osfx() 
External 
-exit External 
_floatfield__dios 
ios: :floatfield 
External 
_initcount__i3lostream. init 
Tostream_init: :initcount 
External 
_main code :BGG8G6E6 
unextbit__3ios 
fos: :nextbit 
External 
_nextword__3ios 
tos; inextword 
External 


-openprot__7fi lebuf 
filebuf::openpret 


External 
_put_7ostreamFc 
ostream: :put(char) 

788608088 
-stdioflush__Jios 
jos: :stdiof lush 

External 
~stdstatus__13lostrsam_initt 
Tostream_init::stdstatus 

Externe} 


7 


Figure F-3. ASM68K Output File {cont.) | 
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LNK68K Linker 


The LNK68K Linker also supports name C++ mangling/demangling. Since the 
mangled name is not easily interpreted, the decoded (or ‘‘demangied’’) name is also 
shown on the linker error message output and map files. In the map file output, C++ 
mangled names can appear in the PUBLIC SYMBOL TABLE section. If a public 
linkage name fits the C++ name mangling pattern, LNK68K will report the C++ 
mangled name as well as the C++ demangled name in the map file. 


Demangling Example 
One encoded name of a function defined in the C++ 1/O stream class library is: 
as__ 18istream_withassignFP9streambuf 


LNK68K will decode the above encoded C++ name into the C++ symbolic source 
name: 


istream_withassign: :operator=(streambuf*) 


Now, you can see that the class istream_withassign contains an overloaded 
operator function (=), which takes one argument of type streambuf*. 


LNK68K will report the mangled name and the demangled name in the public 
symbol table entry of that function in the linker map file: 


PUBLIC SYMBOL TABLE 
SYMBOL SECTION ADDRESS MODULE 
as___18istream_withassignFP9streambuf 


code 000110DE stream 
istream withassign: :operator=(streambuf*) : 


The demangied name of the function is listed in the SYMBOL column of 
as__ 18istream_withassignFP9streambuf. 


Symboi Name Length 


LNK68K’s linkage name limit has been extended to handle 127 characters, instead 
of the standard 31 characters. For symbols that are longer than the line limit, 
LNK68K will continue the symbol on the next line. The SECTION, ADDRESS, 
and MODULE information will start in the corresponding columns af the next line 
following the long symbol name. 


Microtec Research, inc. F-9 
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A link map was generated for simplel.cc running on a UNIX-based host. Figure 
F-4 shows the link map, with areas of interest numbered. These numbered areas are 
described below: 


1. 


The C++ library ccc68kab.1ib is used in addition to the standard 
MCC68K library mcc68kab. lib. 


The initfini section has been placed before the code section using the 
ORDER linker command. 


a-i. These areas show references to the initfini section, a special C++ 
section reserved for pointers to C++ static constructors and destructors. For 
more information, refer to your C++ Compiler Reference Manual. 


This mangled name has been encoded from the C++ source-level symbolic 
name. 


The mangled name (see above) has been decoded to show its demangled 
name. Symbolic names are listed in mangled/demangled pairs. 


These names (prefixed by __ ptb1__ ) are the linkage names for pointers 
to the C++ virtual tables produced by the C++ Compiler. 


These names (prefixed by __ std___) are the linkage names for pointers to 
the C++ static destructors. 


These names (prefixed by __ sti_ _) are the linkage names for pointers to 
the C++ static constructors. 


These names (prefixed by __ vtb1__ ) are the linkage names for pointers 
to the C++ virtual tables produced by the C++ Compiler. 
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CCCEBK V4 Default Linker Command File 


listabs publics, internals 

listmap publics, internale 

farmat ieee 

extern ENTRY * force load of inittalization routine 
. 


If linking with MCC6BK 3.x objs, enable the next 3 lines: 


* 
* 

bd alias code,9 * 9 was default value of $CODESEG in 3.x 
bd alfas zerovars, 14 * 14 was default valua of $0ATASEG in 3. 
* alias vars,13 * 19 was default value of SINITSEG in 3.% 
s alias heap, 15 * 15 was heap section in 3.x 

public 77?7?STACKTOP=$18488 

resmem $6009,$8a00 * reserve stack area 


order literals, strings, const, initfini, code * ROM sections 
order” Vars,zerovars,heap RAM sections 
z 


If using A5-relative data addressing, enable the next 3 lines: 


index ?a5, vars * AS will be pointed to sect vars in entry 
load =mecB8kaSXX. 11b * Modify to access correct library 
load = ccc68ka5XX.11b * Modify to access correct library 


minor change in entry.s): 


initdata vars <ROMaddr> put initialization values at ROMaddr 

load entry.o modify to call _initdata 

load mec68kXX. 11b Modify to access correct library 
* Joad cecGOkXX. 1ib Modify to accese correct library 
LOAD simplei.o ! 
LOAD cecbBkab.Jib 
LOAD mec6Bkab. tib 


s 
s 
s 
s 
3 
* 
*° If using run-time initialization of RAM, enable the next 4 lines (aleo need 
* 
2 
* 
t 
+ 


‘ 


Figure F-4. LNK68K Link Map 
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Microtec Research LNKGBK 


QUTPUT MODULE NAME: simplet 
OUTPUT MODULE FORMAT: IEEE 


SECTION SUMMARY 


SECTION 


literals 


zerovars 
heap 
toports 


ATTRIBUTE 
ABSOLUTE 


NORMAL DATA 
NORMAL DATA 
NORMAL DATA 
NORMAL DATA 


MOOULE SUMMARY 


MODULE 
simptes 


new 
delete 
handler 


placenew 
stream 


cstreams 


streambuf 


SECTION: START 


zerovars : 00814968 
code: 80818188 


S nos: Ahi 1] Hehe 


initfini:@0e108C8 initfini ;@001B6CF 


cade: 44618 
code: 88018256 
vars: 880144E2 
code : B891826E 
code: 68816288 
zerovars: 68014962 
code: 86810286 


ars; @e@p14 


initfint :600100D8 initfini:@6610807 


B144E6 
zerovars d149b4 


zerovars! 644814966 
code: BB8116B8 
vare: B88 146A2 


Version 6.7F 


START 


eaeasaes 
90818080 


G48 144E 

86814968 
@8814aC4 
gagaaaes 


SECTION: END 


END 


GGG6FFFF 
oa61e888 
88018845 


@A8108FF 
6881495) 
888 14AC3 
88614407 
aagaagai 


FILE 


C++ Support 
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LENGTH ALIGN 


gagesee@ = @ (BYTE) 
genee8ee@ 68 (BYTE) 


aeeees7C 862 (WORD) 
@0880164 4 (LONG) 
aBes@864 2 (WORD) 
geaaea82 2 (WORD) 


zerovars:68014961 simplel.o 


code: 88018210 


code:46 

Code; 88818260 

vars: 888144E5 

code : 8881027F 

Code: 08818285 
zarovars: 08814963 

code: 068113BB 
zerovars:auul4g 


Gods: 48812535 
vars: 6681476) 


cec68kab.1tb 
ecc6Bkab.1ib 
ccc66kab. lib 


ccec68kab. lib 
cec68kab. lib 


ecc68kab. 


itfini:@89108D8 initfini :088188DF 


zerovare: 08814967 cec6Skab. 


strings: 88810886 strings: 00019821 
Cinitfini :688100E8 initfini:@@0188E7 


zerovars:686014969 ccc6&kab. 


zerovars: 68814968 
code: 88812536 


nitf ini 38010068 
zerovars: BBU14358 


Figure F-4. LNK68K Link Map (cont.) 


code: 88812843 
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pecbeder tens at pc 


1 lebuf iniitin\ 906 00F9 soseFins 86082 mxcGBkab. lib 
code: piecpele set etoe 


csys68k foports: aaeao008 ioports: aBeeees: mecBBkab. 
strings : 48018822 strings :88018845 
code: 98613CE6 code: 88813F21 
inchrw code: 88013F22 code:46013F29 mcc6Bkab. 
putchr code: 88913F24 code:86813F33 mcc6Bkab. 
SBRK code :86913F34 code:886813F43 mccBBkab. 
ENTRY code :86919F44 :80813FF1 mec6Bkab. 


initfint: g0@1a1¢0 initfints -eaa101ng 
7 


pa 36 
malloc :aaaiarrz 100214 151 mec6Bkab. 
ctype 788818046 188818807 mccBBkab. 
fapen *@8814152 788816255 mec6Bkab. 
fclose +8BB142S6 :6@8142CF mec68kab. 
fflush :88014208 188814335 mcchBkab. 
exit 389814336 :@881438D mec&Bkab. 
setbuf :8881438E 1808143E1 mecGBkab. 
LOI¥ 7BBB143E2 789614400 mec6Bkab. 
iseak :888144DE :806144E1 mccGBkab. 


meee ree ee 


PUBLIC SYMBOL TABLE 


SECTION ADDRESS MODULE 


27? 7HEAP 8@8144C4 
22ST ACKTOP 86818086 . 
ENTRY 88813F44 
— INCHRY 68813F22 
88813F2A 


—88__ 168 gn 8801183E stream 
{etream_ui these ign: zoperator= eae) 
_.as__18ostreamwithsssignFP9streambuf coda 00011176 stream 
ostream.withagsign: :operator=(streambuf*) ‘ 
as__18ostream_withassignFR7ostream code Be811158 stream 
ostream_withassign: :operator=(ostreamk) : 
ae__1Siostream_withassignFP9streambuf code 68811248 stream 
jostrasmwtthessign: :operator=(streambuf* } 
~—88__19iostresmwithassignFR3ios code @081127C' straam 
{ostream_withaesign: :operator=(tos&) ‘ 
—-~8S__31osFRIio0s code 688 18F 28 stream 
1os: :operator=(1os&) 


Figure F-4. LNK68K Map File (cont.) 
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—_ct__ 13 ostream inttFy code 901261C cstreams 
Tostream_init::Iostream_init() 
___ct__18istreamwithassignFy code @B810F5A stream 
istream_withassign::istream_withassignt{ ) 
_—_ct__18ostream_withassignFy code 80114E6 stream 
ostream_withassign: :ostream_withassign() 
___ct__131ostream_withassignFy code 68811198 stream 
jostream_withassign: ; jostream_withassign() 
—_ct__3tosFPSstreambuf code @288163FC stream 
jos:: ios{streambuf* ) 
—_ct__diosFv code @801eF32 stream 
jog::ios() 
—_ct_7filebufFi code 98813B6C ftlebuf 
filebuf::#4lebuf (int) 
_—ct__7f1 lebufF iPcT 1 coda @2013BBE filehuf 
filebuf::f1lebuf(int, char®, int) 
—_ct__7filebufFy code @8013B22 filebuf 
filebut::filebuf() 
-~ct__7istreamFPSstreambuf . code @80185F4 stream 
istraam: :istream(straambuf*) 
~ct_7tistreamFy code 629818882 stream 
istream: : istream() 
__ct__7ostreamFPSstreambuf code 08018608 stream 
ostream: :ostream(streambuf* ) 
——ct__7ostreamFy code 68018862 stream 
ostream: :ostream() 
~~-ct__8iostreamFP9streambuf code @68184E6 = stream 
jostream: : iostream(streambuf* ) 
—ct_.BtostreamFy code 68818762 stroam 
{ostream: : fostream() 
—_ct_SstreambufFPci code BBB12EFA streambuf 
streambuf: :streambuf(char*, int) 
—_ct__SstreambufFy code 6@812ES5 streambuf 
streambuf : :straambuf () 
—~.d1__FPyv code 08618255 -delete 
operator delete(void*) 
dt 13lostream_initFy code 088127A2 cetreams 
lostream_init::*Iostream_init() 
—_ct__181stream_wi thassignFy code @BG1GFDA straam 
istream_uithassign::~istreamwithaselgn() 
——dt__18estream_wi thassignFy code 62011866 straam 
ostream_withaesign: :“ostreamw i thasse1gn( > 
—~—dt__19{/ostreamwithassignFy code 68821218 stream 
Jostreamwithassign: :~{ostream_withassign() 
—dt_Jiosryv code 80618438 stream 
jos: :~ios() 
——dt__7f1 tebufFy code 68613018 fl lebuf 
filebuf::*filebuf() 
-~dt_7istreamFy code 98616664 stream 
istream::~istream() 
—_dt__7ostreamFy cade 88918736 stream 
ostream: : ~ostream( ) 
——dt__flostreamFy code 98818574 stream 
iostream: :“lostream() 

Figure F-4. LNK68K Map File (cont.) 
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_-_dt__SstreambufFy code 9a012F68 streambuf 
streambuf: :~streambuf() 
~—18__7ostreamFPSstreambuf code 99612358 
ostream: :aperator<<(streambuf* ) 
_—_|8_7ostreamFPCc cods 66811838 
2 ostream: :operator<<(const char*) 
_-_18__7ostreamFPy cade ag12492 
ostream: soperator<<(void* ) 
a. 18__70streamFui code 686124F6 
ostream: :operator<<(unsigned int) 
——_1s..708treamFU) code Q@8B8121F2 
ostream: :opsrator<<(unstgned long) 
—~1s__7oestreamF 1 code 88412408 
ostream: :operator<<( int) 
___1s__7ostreamF i code 6861286E 
ostream: ;operator<<{ long) 
—-_nw__FU4 code 0881021E 
operator new(unsigned int) 
—--nw__FUIPy code 99918288 ptacenew 
operator _new(unsigned int, void* 
ptbl__17ostream__iostream__19iostream_withassign.__stream_stream_cxx 
vars 68014516 stream 
___ptbl__18istream_withassign____stream stream cnx 
vars 9881458E stream 
~-.-ptb1__18o0stream_withassign__stream_stream_crxx 
. vars 86314586 stream 
——ptbl__191ostream_withessign____stream_stream_cxx 
vars 8081454E stream 
_.-ptb}__dios__18istream_withassign streem.stream cxx 
a vars 8B14SA2—s stream 
—~ptbl_dios__180stream_withassign___stream_stream crx 


a vare BQB1456A ~—s stream 
6 —w || —_ptbl__3tos__191ostream_withaseign__.stream_stream_cxx ; 

vars BAB 14532 stream 
——_ptbi__3ios_.7istream___stream_straam_cxx 

vars BBB14SDA stream 
—-ptb]__3tos__.7ostraam____stream_streamcxx 

vars B@814612 stream 
—~—ptbl__310s__81ostraam___.stream_stream_cxx 

vars BGG 14644 stream 
——Pptbl_3ios, stream_stream_cxx vars @961469E stream 
———ptbl__7f 4 lebuf streamfilebufcxx vars @201495A filebuf 
——ptbl._7istrean____stream_streamcxx vars @89145F6 stream 
__-ptb1__7estream_8iostream____stream_stream_cnx = 

vars 68014666 stream 
—ptbl__?ostream___stream_streamcxx vars @801462E stream 
—__ptbl__ high drelr rumah eter eto op vars 66014682 stream 

ptbt + 
BQG14BEA streambuf 

—_rs__7istreamFPUc 86011788 in 
istream: :operator>>(unsigned char*) 
~—_rs_7istreamFPc B8B115F4 in 
istream: :aperator>>(char*) 
_ std__streamcstreams_cxx_stdstatus_ code 49612848 cstreams 


Figure F-4. LNK68K Map File (cont.) 
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—_std_____stream_fi tebuf_cux_last_op. 


——std____stream_in_cxx_satwhi te_ 
—_std_____stream_outicxndigiti. 


__ std_____streamstream_cxx_stdiof lush 


Wed Aug 1 10:36:29 1998 


__std_____stream streambuf_cxx_doal locate_ 


ost etrea 
sti 
sti stream_tn_cxx_eatwhite_ 
__sti____stream_out_cxx_digiti_ 


__-sti____stream_stream_cxn_stdiof lush_ 
stream_streambuf_cxx_doal locate_ 


—sti 


7 vtbi__17ostream__iostream._19iostream_uithaseign 


—_vtb1__18istream_withassign 
_—vtbi_ 18ostream_withasstgn 
_.vtbl_ 19icstream_withassign 
——vtbl_dios 
_..vtbl__3ios_18istream_withassign 
__vtbl__3ios__ 180stream_withassign 
__vtbl__3ios__19iostream_withassign 
——vtbl__3ics__7istream 
___vtb1__3ics__7ostream 
_—vtbt_3ios__8iostream 
—vtbi__7f1 lebuf 
—__vtbl__7istream 
—..vtbl__7ostream 
——vtb1l__7ostream_Siostream 

a. vtbi__Biostraam 


—auldiv 

—auirem 

avail 

~_badlist 

—ctbuf 

—cttype_ 

—exit 
—_fp_contro] 
—fp_status 
—-getavail 

—iob 

__lastp 

—-ldiv 

—Ilrem 

~_—menba se 

_—_new handler 
__randy 
—simulated_ input 
—simulated output 


etream_fi lebuf_cxx_)ast_op_ 


vars 
vars 
vare 
vars 
vars 
vars 
vars 
vars 
vars 
vars 
vars 


zerovars 
zerovars 
zerovars 
const 
code 
zerovars 
zerovars 
code 
zerovars 
zerovars 
code 
code 
zerovars 
vars 
zerovars 
Joports 
toports 


8615006 
68611646 
68812524 
@881134A 


@881305E 
9892888 
83813CC6 
#9811896 


88812514 
68811394 


0861304E 


Q86144FE 
988145A6 
8881455 
68014536 
08814666 
8914584 
90914552 
@881451A 
66914502 
@Q814SFA 
68814692 
890148F2 
@8614S0E 
88814616 
B88 1464E 
B8814664 
06834882 
B88 143E2 
@B81449E 
888 1441E 
08814462 
08814978 
98814986 
8G814AA8 
80618046 
00913FC@ 
€061497C 
8081497E 
8OB13FF2 
88014984 
88814978 
@88143E6 
688 144A2 
@8814A8C 
@88144E2 
@0914490 
eanegeae 
gen8eee1 
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filabuf 

stream 

stream 

stream 

stream 

streambuf 

LDIV 

LDIV 

LDIV 

LDIV 

LINKER GENERATED 
LINKER GENERATED 
LINKER GENERATED 
ctype 

ENTRY 

LINKER GENERATED 
LINKER GENERATED 
malloc 

LINKER GENERATED 
LINKER GENERATED 
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LINKER GENERATED 
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—uidiv cade 00814422 LOIV 

—uirem code 86814486 LDIV 

wadjustfield_dios vars @8B144F2 stream 

jos: :adjustfield 

wattach__7filebufF i code 689192FE filebuf 

filebuf::attach(int) 

_basefield_<3ios vars 800 144F4 stream 

ios: :basefield 

_bitalloc__3iosSFv code 80011376 stream 

jos: :bitalloc . 

_cerr vars 68B147FE cstreams 

cin vars 88814776 cetreams 

clog vars 2014848 cstreams 

Close code @8613E2E ceys68k 

_Close__7filebufFy code 08813732 fi lebuf 

filebuf::closs() 

_cout vara 88014780 estreama 

-creat cade GBB13E1A csys68k 

~do_ipfx__7istreamF 1 code 88818084 stream 

istream: :do_ipfx(int) 

—do_opfx__7ostreamFy code @8B14E78 stream 

ostream: :do.opfx() 

-do_osfx__7ostreamFy code 8081BEE2 stream 

ostream: :do_osfx() 

_doallocate_S9streambufFy code BBB129BA streambuf 

streambuf ::doallocate() 

-eatwhite__7istreamFy cade 08811442 in 

istream: seatwhite() 

errno zerovars 08014974 LINKER GENERATED 
\ wexit code 08614336 entt 

_fclose code 60614256 fclose 


ae _fflush code 68814208 ff lush 
_fill_dlosFe code 88018032 stream 
jas: :f4111 (char) 

-ftags__SiosF code 68818040 stream 
jos: :f tags( long) ; 
-floatfield__3ios vars G0B144F6 stream 
jos::floatfield 

_flush_7ostreamFy code 886186BE stream 
ostream: :f tush{> 

_fapen code 88614152 fapen 
_free code 888 148R2 malloc 
~init__diosFPSstreambuf code @981636C stream 
jos: :init(streambuf*) 

_initcount__13lostraam init vars 89614772 cstreams 
Iostream_init::initcount 

—iword__3iosF1 code @801191A stream 
1os::iword(int) 

—Jastlop_.7f i lebufFy code 80013156 #1 lebuf 
filebuf:: lastop() 

_lseek code 08B144DE lseek 
nain code @80181E6 simple1 
_mal toc code @8013FFA malloc 
-nextbit_3ias vars @BB144EA stream 


Figure F-4. LNK68K Link Map (cont.) 
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jos; smextbit 

_nextword__ 3108 BAB144EE stream 
jos: :nextword 

open @@130C8 ceys6ak 
~open__7f1 lebufFPEe1T2 08813172 filabuf 
filebuf::opan(const char*, int, int) 

-openprot__7#f 1 labuf BBB 146EE 4 lebuf 
fi lebuf::openprot 

over flow._7f i lebufF 4 68813368 ftlebuf 
filebuf: overflow int) 

overflow __SstreambufF i O98129E6 streambuf 
streambuf: :overflow(int) 

_pbackfail__9streambufF i @6812ACB streambuf 
straambuf: :pbackfail(int) 

_precision__diosFi 60818044 stream 
jos: :precision( int) 

_putback_7istreamFc @80117C6 in 
istream: :putback(char ) 

-pword__3iosF i 68011348 stream 
jos: :pword( int) 

read @8813E62 esys68k 
-sbrk 80B13F34 SBRK 
-seskg__7istreamFl 69810B88 stream 
istream: :seekg{ long) 

_seekg__7istreamF 18seek_dir 8814870 stream 
istream: :seakg(long,seak_dir) 

~baekoff__7fi lebuff 18seek_dtri 88013808 fi labuf 
fi lebuf: :seekoff{ long, seek_dir, int) 

_seekoff__SstreambufF 1Bseak_dirt 94812846 streambuf 
streambuf ::seekoff(long,seek_dir, int) 

-6eekp__7ostreamF} 88B18A1C stream 
ostream: : saekp( long) 

_seekp__7ostreamF 16seek_dir 68818498 stream 
ostream: :seekp( lang, seek_dir} 

~seekpos_YstreambufF 14 68012B1A streambuf 
streambuf: :seekpos( long, int) 

~set_new_handler__FPFy_v 8601626E handler 
_setbouf B86143BE setbuf 
_betbuf__7fi lebufFPei B8013CSC Ffilebuf 
filebuf::setbuf(char*, int) 

_setbuf__SstreambufFPUct 88912E2C streambuf 
streambuf ::setbuf (unsigned char*, int) 

-setbuf_SstreambufFPci 08012014 streambuf 
streambuf::setbuf{char*, int) 

-setf__3iosF! @6816C82 stream 
jos: :setf( tong) 

setf__3iosF1T1 60818C58 stream 
jos; :setf( tong, long) 

_8tdioflush_3ios 66G144E6 stream 
ios::stdiof lush 

_stdstatus__13Iostream_init 8881476E cstreams 
Tostream init: :stdstatus 

_sync_..7fi lebufFy 668137FE filebuf 
filebuf::sync() 


Figure F-4. LNK68K Link Map (cont.) 
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-sync__9streambufFy 
streambuf::sync() 
_tellg_7istreamFy 
istream::tellg() 
_tellp_7ostreamFy 
ostream: :tel1p() 


_tie_3iosFP7ostream 


ios: :tie(ostream*) 


_underf low__7# i lebufFy 
fi lebuf: :underf low) 
under f low__SstreambufFy 
streambuf ::underf low() 


_unsetf__31osFt 
1os::unsetf( long) 
_uresize__3iosF i 
fos: :uresize(int) 
write 


_X_snextc__IstreambufFy 
streambuf; :x_snextc() 


_Kalloc__3iosSFy 
jos: :xalloc 
_xget__71istreamFPc 


istream: :xget(char*) 
_xsgetn__SstreambufFPci 
streambuf : :xegetn(char®, int) 
_xsputn__SstreambufFPCci 
streambuf::xsputn(const char*, int) 


Idivt 
Imodt 
uldivt 
ulmodt 


START ADDRESS:  a8013F44 


Load Completed 
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80814442 
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streambuf 
etream 
stream 
straam 
fi lebuf 
streambuf 
stream 
stream 


csys68k 
straambuf 


stream 

in 
etreambuf 
streambuf 
LDIV 

LOIV 


LOIV 
LOIV 
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LIB68K Librarian 
LIB68K will automatically demangle C++ names when they are encountered if a 
given symbol name fits the C++ name mangling scheme. If there is a C++ symbolic 


source-level name available for the symbol name being processed, LIB68K will 
display the C-++- symbolic name in the next line of the low-level name: 


<low-level mangled c++ name> 
C++ NAME: <ct++ demangled symbolic source-level name> 


Example: 


_flush__ 7ostreamFv 
C++ NAME: ostream: :flush() 


In the example above, the mangled name shows the function signature. The 
demangled name shows that there is a function f1ush () in the class ostream which 
does not take any arguments. 


Figure F-5 shows a portion of the listing file (~1 option) created by the command 
line: 


1ib68k -1 ccc68kab.lib 


information, since the C++ name encoding scheme encrypts function prototype 


Note that the displayed C++ source-level names include function prototype : ; 
information into the function signature. 


Areas of interest are numbered as described below: 


1. Mangled function signatures are shown. 


2. Demangled function signatures are shown. In the first case, a public 
function genericerror, which passes two arguments, is declared. In the 
second case, the new operator has been overloaded. You can use the 
standard new operator with a type specifier (to allocate dynamic storage) or 
you can use your user-defined new function, which passes a void pointer. 
The compiler will determine which definition you are applying to new by 
its use in your C++ program. 
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Library being built mec68kab.1ib 


Module Size Processor 
generic ..- 423 68688 
aseee* PUBLIC DEFINITIONS ##*e"* 
ta _genericerror__F4Pc 
2a G++ NAME: genericerror(int,char*) 


aexese EXTERNAL REFERENCES **#088* 
-abort 
_fprintf 
—iob 


Public Count 
External Count 
Common Count = 


Module Size Processor 
NeW ... S11 66888 
seseve PUBLIC DEFINITIONS seeee® 
ib aay FU 
2b C++ NAME: operator new(unsigned int) 


awesee EXTERNAL REFERENCES #***** 
—_new_handler 
—_mat toc 


Public Count 
External Count 
Common Count = 


Module Size Processor 
delete ... 263 6eee8 


weasae PUBLIC DEFINITIONS eoeees 
_.d1__FPy 
C++ NAME: operator delete(void?) 


sewese EXTERNAL REFERENCES ***83* 
free 


Public Count 
External Count 
Common Count = 


Figure F-5. Portion of LIBG8K Listing Fite 
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Module Size Processor 
handler ... 335 68280 


wennas PUBLIC DEFINITIONS *#**08 
__new_handler 
_set_now_handier__FPFy_v 


Public Count 2 
External Count = 8 
Commen Count = 


Module ‘Size Processor 
—VOC os 813 68288 


#eeee* PUBLIC DEFINITIONS ****** 
——vec_delate 
—_— Vec_neaw 


seexes EXTERNAL REFERENCES ***#2* 
——nm_FUi 
C++ NAME: operator new(unsignead int) 
—Imu 
——.d1_FPyv 
C++ NAME: operator delete(void*) 


Public Count 
External Coun 
Common Caunt 


Module Size Processor 

Placenew ... 239 66¢88 ( ) 
eezees PUBLIC DEFINITIONS *###** 

——Pu__FUiPy 


C++ NAME: operator new(unsigned int,void*) 


Public Count =i 
External Count = @ 
Common Count = B 


Module Size Processor 
pure ... 254 68888 


sasens PUBLIC DEFINITIONS ****¢* 
—_.pure_virtual_called 


sesene EXTERNAL REFERENCES ###088 
-abort 


Public Count 
External Count 
Common Count = 


Figure F-5. Portion of LIB68K Listing File {(cont.) 
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Module Size Processor 
stream ... 9763 68008 


vaeee® PUBLIC DEFINITIONS ***#*** 
_seekg__7istreamF] 
C++ NAME: tstream::seekg( long) 
_seskg__7istreamF 1Bseek_dir 
C++ NAME: istream: :seakg( long, seek_dir) 
-tellp__7ostreamFy 
C++ NAME: ostream: :tel)p() 
-basefteld__dios 
C++ NAME: 108: :basaf{eld 
_flush_.7ostreamFy 
C++ NAME: ostream: :flush() 
-xal loc__3iessFy 
C++ NAME: jos::malloc 
_f111__31osFc 
C++ NAME: 1os::f411(char) 
—..as__18istream_withassi gnFPSstreambuf 
C++ NAME: istream_withassign: :operator=(streambuf* ) 
—as__16istreamwithassignFR7istraam 
C++ NAME: istream_withassign::operator=(istream&) 
_—_as__idostream_withassignFPSstreambut 
C++ NAME: ostream_withassign: :operator=(streambuf® ) 
—_as__ifostream_withagsignFR7ostream 
C++ NAME: ostream_withassign: :operator=(ostream&) 
—--88__19{ostream_wi thassignFPSstreambuf 
C++ NAME: iostream_withassign: :operator=(streambuf* ) 
( ~--88__191ostream_withase i gnFRStos 
C++ NAME: jostream_uithassign: :operator=( iosk) 
—~—88__JiosFR3ics 
C++ NAME: ios;soperators(ius&) 
-unsetf__3tosFt 
C++ NAME: jos: :unsetf( long) 
—beekp__7ostreanF t 
C++ NAME: astream::seekp( long) 
~seaekp__7ostraamF 18seek_dir 
C+ NAME: ostream::seekp( long, saak_dir) 
_-ptbt__it7astream__iostream__ 19iostream_withassign__stream_straam cxx 
——ptb]__161straam_withass{gn____stream_stream_cxx 
—~—ptb1__1Bostream_withassign stream_stream_cxx 
——-ptb1__19fostream_withassign___stream_straam_cxn 
——ptb1__3ias__181strean_withassign__stream stream _cxx 
—-ptbl__3ios__ t8ostream_withassign, stream_stream_cxx 
———ptb1__31o0s_ 19lostream_withass{gn__stream_straam_cxn 
—-pthl__3ios__7istream___stream_stream_cnx 
—_ptbl__3ios_7ostream_ stream_stream_cxn 
—-ptb)__3ios_8icstream, stream_stream_cxn 
—-ptbl__sios etream.stream_cxx 


Figure F-5. Portion of LIBG8K Listing File (cont.) 
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_—_pto1__7istream____stream_stream_cxx 
___ptb1__7ostream__8{ostream____stream_stream_cxx 
—-ptbt_.7ostream___stream_stream_cxx 
——_ptb1__Biostream etream_stream cnx 
___std____stream_stream_exx_stdiof lush_ 
-hextword__Jiss 

C++ NAME: jos::nextword 
___vtb1__17o0stream__{ostream__19iostream_withassign 
—_vtb1__iBistream_wi thassign 
—_vtbl__180stream_withassign 
___vtb1_19iostream.withassign 
—_vitbl__Sios 
___vtb1__3ios__18istream_withassign 
___vtbl__dios__18ostream.withassign 
___vtb}__3ios__19iostream_withassign 
_._vtbhl__dios__7istream 
—_vtbl__3ios_7ostream 
——_vtbl__3ios__Biostraam 
—_vtbi__7istream 
—_vtbl__7ostream 
—_vtbl_.7ostream__@iostream 
—vtol__Alostraam 
—__ct__i6istream_withassignFv 

C++ NAME: tstream_withassign: :istream_withassign() 
__.ct__i8astream_withasstgnFy 

C++ NAME: ostream_withaesign: :ostream_withassign() 
—_ct__iSiostream_withassignFy 

C++ NAME: jostream_withassign: : fastream_utthassign() 
—_ct__diosFP9streambuf 

C++ NAME: jos::ios(streambuf®) 
—_ct_diosFy 

C++ NAME: jos::ios() 
_._Ct__71streamFP9streambuf 

C++ NAME: istream::istream(streambuf*) 
—_ct__7istreamFy 

C++ NAME: igtream::istream() 
___Ct__7ostreamFP9streambuf 

C++ NAME: ostream: :ostream(streambuf® ) 
_--ct__7ostreemFy 

C++ NAME: ostream::ostream{) 
——ct__SiastreanFP9streambuf 

C++ NAME: fostream: :iostream(strsambuf® ) 
—_ct__8{ostreamFy 

C++ NAME: fostream: :iostream() 
—_ct__18{stream_uithassignFy 

C++ NAME: istream_withassign: :~istreamwithassign() 
—_dt__ifostream_withassignFy 

C++ NAME: ostream_withassign: :*ostream_withassign(> 
—-ot__1Hostream.withassignFy 

C++ NAME: jostream_withassign: :“iostream_withassign() 
--dt__diosFy 


Figure F-5. Portion of LIB68K Listing File (cont.) 
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C++ NAME: jos::“1os() 
___dt__7istreamFy 

C++ NAME: istream::“tstream(} 
——dt__7ostreamFy 

C++ NAME: ostream: :“ostream() 
—_dt_8iostreamFy 

C++ NAME: iostream::“iostream() 
_uresize_diosFi 

C++ NAME: jos::uresize(int) 
-pword__SiosFi 

C++ NAME: tos: :pword(int) 
_tie_.dtosFP7ostrsam 

C++ NAME: jos::tie(ostream*) 
-precision._JiosFi 

C++ NAME: ios::precision( int) 
_setf__diosF) 

C++ NAME: jios::setf(long) 
—setf_3SiosFITL 

C++ NAME: jos::setf(long, long) 
—flags__3iosF I 

C++ NAME: jos::flags( tong) 
floatfield_3ios 

C++ NAME: jos::floatfield 
-do_ipfx__7istreamF i 

C++ NAME: istream::do_ipfx(int) 
-Stdioflush__Jios 

C++ NAME: ios::stdiofiush 
.do_opfx__7ostreamFy 

C++ NAME: ostream: :do_opfx() 
_bitalloc__d1asSFv 

C++ NAME: 1os::bitalloc 
-init._JiosFP9¥streambuf 

C++ NAME: fos::init(streambuf*} 
~iword__diosFi 

C++ NAME: 1os::4word(int) 
—do_osfx__7ostreamFv 

C++ NAME: ostream: :do_osfx() 
-adjustfield__dios 

C++ NAME: tos::adjustfield 
anextbit__Jios 

C++ NAME: tos::nextbit 
-—sti stream_stream_cxx_stdioflush_ 
_tellg__7istreamFy 

C++ NAME: istream::tellg{) 


Figure F-5. Portion of LIBG8K Listing File (cont.) 
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O 


eee EXTERNAL REFERENCES ****8* 

—ns_FUI 

C++ NAME: operator new{unsigned int) 
_satwhite__7istreamFy 

C++ NAME: istream::eatwhite(} 
-—ct_1{3lostream_initFy 

C++ NAME: Iostream_init::Iostream_init() 
——dt__13lostream_initFy 

C++ NAME: fos: :uresize(int) 
_pword__3iosF4 

C++ NAME: Iostream_init::initcount 
_stdstatus__13Iostream_init 

C++ NAME: Iostream_init: :stdstatus 
—-d1__F Py 

C++ NAME: operator delete(void*) 


Public Count 86 
External Count = 7 
Common Count = 


C 


Figure F-5. Portion of LIB68K Listing File (cont.) 
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Object File Formats: 
Appendix G 


This appendix describes the Motorola S-Record absolute object file format. 


S-Record Format 


A file in Motorola S-Record format is an ASCII file. Absolute object files consist 
of optional symbol table information, data specifications for loading memory, and 
a terminator record. 


{$$ (module_record) 
symbol records 

$$ [module_record] 
symbol records 

$$} 

header record 

data records 

record count record 
terminator record 


Module Record (Optional) 


Each object file contains one module record for each module that is a component of 
it. This record contains the name of the module. For relocatable objects created by 
the assembler, there is only one module record, whose name comes from the IDNT 
directive. For absolute objects created by the linker, there is one module record per 
input relocatable object file, plus one for the linker whose name comes from the 
NAME command. 


Example: 


$$ MODNAME 
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Symbol Record (Optional) 


As many symbol records as needed can be contained in the object module. Up to 4 
symbols per line can be used, but it is not mandatory that each line contain 4 
symbols. A module can contain only symbol records. 


Example: 


APPLE $00000 LABEL1 $0D0C3 
MEM SOFFFF ZEEK $01947 


The module name associated with the symbols can be specified in the 
module_record preceding the symbol records. 


Example: 
$SMAIN 


Symbols are assumed to be in the module named in the preceding module_record 
until another module is specified with another module_record. Symbols defined by 
the linker’s PUBLIC command appear following the first module record, which 
indicates the name of the output object module specified by the linker’s NAME 


command. 
Header Record 
Each object module has exactly one header record with the following format: 
$00600004844521B 
Description: 
| 
so Identifies the record as a header record. 
06 The number of bytes following this one. 
0000 The address field, which is ignored. 
484452 HDR in ASCIL. 
1B The checksum. 
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$-Record Format 


Data Record 


A data record specifies data bytes that are to be loaded into memory. The format for 
such a record is shown in Figure G-1. 


12 34 5678910 11..41 42 4344 


SID byte load data...data check 
count address 1 n sum 


Figure G-1. Data Record Format for 24-Bit Load Address 


Column Description 


1 Contains S which indicates the start of a record in Motorola S- 
Record format. 

2 Contains a digit identifying the record type. For data records, this 
digit is 2 (for 24-bit addresses) or 3 (for 32-bit addresses only if 
CHIP CPU32, CHIP 68020, CHIP 68030, or CHIP 68040 was 
specified). 

3to4 Contains the count of the number of bytes following this one within 
the record. The count includes the checksum and the load address 
bytes but not the byte count itself. 

For 24-bit load address: 
5to10 Contains the load address. The first data byte is to be loaded into this 


address and subsequent bytes into the next sequential address. 
Columns 5 and 6 contain the high order address byte, columns 9 and 
10 contain the low order address byte. 


11to42 Contains the specifications for up to 16 bytes of data. 


For 32-bit load address: 


5 to 12 


Contains the load address. The first data byte is to be loaded into this 
address and subsequent bytes into the next sequential address. 
Columns 5 and 6 contain the high order address byte, columns 11 
and 12 contain the low-order address byte. 


13to42 Contains the specifications for up to 16 bytes of data. 
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The last two columns in the data record contain a checksum for the record. To 
calculate this, take the sum of the values of all bytes from the byte count up to the 
last data byte, inclusive, modulo 256. Subtract this result from 255. 


Record Count Record 


The record count record verifies the number of data records preceding it. The format 
for such a record is shown in Figure G-2. 


12 34 5678 910 


SID byte # of data check 
count records sum 


Figure G-2. Record Count Record Format 


Column Description 


1 Contains § which indicates the start of a record in Motorola S- 
Record format. 
2 Contains 5 which indicates a record count record. 


3to4 Contains the byte count 03. 


5to8 Contains the number of data records in this file. The high-order byte 
is in columns 5 and 6). , 


9to10 Contains the checksum for the record. 
Example: 


$503010DEE 


The example above shows a record count record indicating a total of 269 records 
(0x010D) and a checksum of OxEE. 
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Dm 
Terminator Record 
A terminator record specifies the end of the data records. The format for such a 
record is shown in Figure G-3. 


12 34 5678910 


SID byte load 
count address 


Figure G-3. Terminator Record Format for 24-Bit Load Address 


Column Description 


1 _ Contains S which indicates the start of a record in Motorola _ 
S-Record format. 

2 Contains 8 to indicate a 24-bit load address. It contains 7 for CHIP 
CPU32, CHIP 68020, CHIP 68030, or CHIP ane to indicate a 
32-bit load address. 

3to4 Contains the byte count 04. 

For 24-bit load address: 


5to10 Contains the load address which is either set to zero or to the starting 
address specified in the END directive (there are no data bytes). 


11to12 Contains the checksum for the record. 
For 32-bit load address: 


5to12 Contains the load address which is either set to zero or to the starting 
address specified in the END directive (there are no data bytes). 


13to 14 Contains the checksum for the record. 
Example: 
S804000AF0001 


The above example shows a terminator secors with a 24-bit load address of 
Ox000AFO and a checksum of 0x01. 
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Not Supported 
in Future Releases: 
Appendix H 


This appendix describes commands that are being phased out and will not be 
supported in future releases. If you have existing software using these commands, 
replace them with the new commands. 


Linker Invocation Changes 


VMS 


The /riacs="flag_list" linker command line option will not be supported in future 
releases. The current linker command line syntax is shown below: 


L68K [ /ABSOLUTE[=absolute_file) | /NOABSOLUTE ] 
| /CommanD<conunand | [ /FLAGS="flag_list" } 
{ /FORMAT=format ] [ /HP | /NOHP ] 
{ /LIBRARY=library |] [ /MAP=map_file | /NOMAP ] 
{ /ossect=relocatable_file | [| /REFERENCE=name] 
{ /OPTION command_file | object_file{, object_file]...} 


where the standard descriptions apply (see Chapter 2, VAX/VMS User’ s Guide) and: 


FLAGS="flag_list" 

F="flag list" Enables and disables the linker control flags (see 
Table H-1). If just the flag letter is used, the flag is 
enabled; if the flag letter is preceded by a minus sign (-), 
the flag is disabled. Multiple flags are separated from 
each other by a space or a comma. A flag list with flags 
separated by a space must be enclosed in double quotes. 


Flags entered on the command line enable and disable internal linker control 
switches. Linker command line flags for flag_list in the FLAGS="flag_list" option 
are listed im Table H-1. Multipte flags are separated from each other by a comma or 
a space. Those separated by a space must then be enclosed within double quotes. If 
conflicting flags are specified, the first flag overrides the second one. Flags may be 
negated by preceding the flag letter by a minus sign (-). 
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Table H-1. VMS Linker Command Line Flags 


Flag Meaning (positive form) 


Cc Prints the external symbol cross-reference table on the 
listing. This flag is equivalent to the linker command 
LISTMAP [NO]CROSSREF. 
(default: -C) 


D Places external definition symbols in the output object 
module. This flag is equivalent to the linker command 
LISTABS (NO]PUBLICS. 
(default: -D) 


I Generates absolute output in IEEE-695 format. It also sets 
the D and S flags. The I flag is equivalent to the linker 
command FORMAT IEEE. 


The negative form of this flag (-I) indicates that the Motorola 
S-record format will be used for the absolute output file. 
(default: I) 


Oo Produces an output object module. 


For more information on this flag, see the linker command 
FORMAT NOABS in the Microtec Research ASM68K 
Reference Manual. 

(default: O) 


P Places any local symbol present in the input modules into the 
linker symbol table. This flag is equivalent to the linker 
command [NO]DEBUG_SYMBOLS. 

(default: P) 


S Writes the local symbol table to the output object module. 
The linker automatically sets this flag when you designate 
HP-OMF or IEEE-695 object output. This flag is equivalent 
to the linker command LISTABS (NOJINTERNALS. 
(default: S) 


T Prints the local symbol table on the output listing. This flag 
is equivalent to the LISTMAP [NOJINTERNALS linker 
command. 

(default: -T) 


x Prints the external definition symbol table on the output 
listing. This flag is equivalent to the linker command 
LISTMAP [NO]PUBLICS. 
(default: -X) 
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UNIX/DOS 


The -£="flag_list" linker command line option will not be supported in future 
releases. The current linker command line syntax is shown below: 


Ink68k [-c command file] [-o output_objectfile) 
{-C command} {-t flag_list) (-¥ format) 
[-h] (-H link_symfile] [-1 library} 
{-m] [-M mapfile] {-r] [-u name] 
{input_object_file[,input_object_file]...} 


where the standard descriptions apply (see Chapter 3, UNIX/DOS User’s Guide) 
and: 


-£ flag _list Enables and disables the internal linker control flags (see 
Table H-2). If just the flag letter is used, the flag is enabled; 
if the flag letter is preceded by a minus sign (-), the flag is 
disabled. Multiple flags are separated from each other by a 
space or a comma. A flag list with flags separated by a space 
must be enclosed in double quotes. 


Flags entered on the command line enable and disable internal linker control 


switches. Linker command line flags for flag_list in the -f="flag_list" option are 
C listed in Table H-2. Multiple flags are separated from each other by a comma or a 
Ss: space. Those separated by a space must then be enclosed within double quotes. If 


conflicting flags are specified, the first flag overrides the second one. Flags may be 
negated by preceding the flag letter by a minus sign (-) or the word no. 


& 
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Table H-2, UNIX/DOS Linker Command Line Flags 


Flag Meaning (positive form) 


c Prints the external symbol cross-reference table on the 
listing. This flag is equivalent to the linker command 
LISTMAP [NO]CROSSREF. 

(default: -c) 


_ Places external definition symbols in the output object 
module. This flag is equivalent to the linker command 
LISTABS [NO]PUBLICS. 

(default: -d) 


i Generates absolute output in IEEE-695 format. It also sets 
the d and s flags. This flag is equivalent to the linker 
command FORMAT IEEE. 

(default: i) 


o Produces an output object module. For more information 
on this flag, see the linker command FORMAT NOABS 
in the Microtec Research ASM68K Reference Manual. 
(default: 0) 


p Places any local symbol present in the input object mod- 
ules into the linker symbol table. This flag is equivalent to 
the [NO]DEBUG_SYMBOLS linker command. 

(default: p) 


s Writes the local symbol table to the output object module. 
The linker automatically sets this flag when you designate 
HP-OMF or IEEE-695 object output. This flag is 
equivalent to the LISTABS [NOJINTERNALS linker 
command. 
(default: s) 


t Prints the local symbol] table on the output listing. This flag 
is equivalent to the LISTMAP [NOJINTERNALS linker 
command. 

(default: -t) 


x Prints the external definition symbol table on the output 
listing. This flag is equivalent to the linker command 
LISTMAP [NO]PUBLICS. 

(default: -x) 
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LIST and NLIST Linker Commands 


The LIST and NLIST commands are no longer accepted. They have been replaced 
with [NO]JLISTMAP and [NO]LISTABS commands. However, LIST and 
NLIST are still presented here along with their equivalent, more mnemonic 
commands to show the relationship between them. 
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LIST — Lists Specified Elements 


Syntax 


LIST option{, option]... 


where an option is 


{CiDITIOILPYRISt{T!X} 


Description 


Cc 


Produces a cross-reference listing. The List c has been 
replaced by LISTMAP CROSSREF. 
(default: no cross-reference listing) 


Places PUBLIC symbols (external definitions) in the output 
object module. The List p command has been replaced by 
LISTABS PUBLICS. 

(default: no external definitions) 


Generates absolute output in MRI-IEEE format. The Lrst 
I has been replaced by FORMAT IEEE. 
(default: IEEE format) 


Produces an object module. The List o command has been 
replaced by FORMAT NOABS. 
(default: 0) 


Places symbols which are present in the input modules 
(ocal) into the linker’s local symbol table. This affects only 
Motorola S-Record output files. 


The List © command can be tumed off and on between 
LOAD commands. Its purpose is to exclude local symbols 
from particular modules because of duplicate symbol 
conflicts. The List P command has been replaced by 
DEBUG_SYMBOLS. 

(default: P) 


Generates relocatable output in MRI-IEEE format that is 
suitable for incremental linking. The List R command has 
been replaced by FORMAT INCREMENTAL. 

(default: TEEE format) 


Writes the linker’s local symbol table to the object module 
(for debugging purposes). The linker automatically sets this 
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option when you designate HP-OMF or IEEE-695 object 
output; otherwise, this option is the default. This option has 
different implications depending upon the output file format 
as described: 


S-Records | Symbols are written to the S-Record absolute 
file in a non-Motorola format. Note that most 
S-Record readers will not recognize this 
format. Writing local symbols to the 
Motorola S-Record absolute files can cause 
duplicate symbols. 


HP 64000 _—‘ The s flag should never be tured off when 
producing HP format absolute files. If you do 
so, you will get errors in the linker symbol 
files, 


IEEE The s flag specifies that debugging informa- 
tion be written to the IEEE absolute output 
file. 


The tist s command has been replaced by LISTABS 
INTERNALS. 


T Lists the linker’s local symbol table on the list output device. 
The List vT command has been replaced by LISTMAP 
INTERNALS. 
(default: no local symbol table in the output listing) 


x Lists the linker’s PUBLIC symbol table on the list output 
device. The List x command has been replaced by 
LISTMAP PUBLICS. 
(default: no PUBLIC symbol table in the output listing) 


The LIST command generates listings of the elements specified. The defaults are: 
symbol tables are not listed, an object module is generated, symbols are not placed 
into the output object module, and local symbols are not purged from the input 
object modules. 


Local symbols are those placed into the object module by the assembler which are 
not extemal definitions. Placing both XDEFs and local symbols into the output 
object module can cause duplicate symbols to exist in the module. Typically, either 
the local symbols placed into the object modules by the assembler or XDEFs wili 
be placed in the output object module. This is the case because the OPT D directive 
in the assembler forms a symbol table which includes both local symbols and 
XDEFs. The LIST options specified will remain in effect through all modules until 
another LIST or NLIST command is encountered. 
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LIST options are separated by one or more blanks or commas. Y 


Example 


LIST T,X * List local and public symbol tables. 


G 
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NLIST — Does Not List Specified Elements 
Syntax 
NLIST option[, option]... 
where an option Is 
{cIDIOIPISITIX} 
Description 


c Inhibits generation of a cross-reference listing. The NLIST C 
command has been replaced by LISTMAP 
NOCROSSREF. 
(default: c)} 


D Does not place PUBLIC symbols in the output object 
module. The nuist bp command has been replaced by 
LISTABS NOPUBLICS. 
(default: p) 


0 Inhibits generation of an output object module. 
(default: generates an output object module) — 


P Prevents symbols which are present in the input modules 
(local) from being placed in the linker symbol table. This 
affects only Motorola S-Record output files. The List pP 
option can be turned off and on between LOAD commands. 
Its purpose is to exclude local symbols from particular 
modules because of duplicate symbol conflicts. The nLIst P 
command has been replaced by NODEBUG_SYMBOLS. 
(default: places local symbols in the linker symbol table) 


Ss Does not write the local symbol table to the object module 
(for debugging purposes). For IEEE output, debug 
information is stripped from the output object file. The 
NLIST Ss command has been replaced by LISTABS 
NOINTERNALS. 

(default: writes local symbol table to object module) 


T Does not list the local symbol table on the list output device. 
The NLIST T command has been replaced by LISTMAP 
NOINTERNALS, 
(default: tT) 


Microtec Research, inc. : H-9 


LIST and NLIST Linker Commands Not Supported in Future Releases 
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x Does not list the PUBLIC symbol table on the list output 

device. The NLIst x command is replaced by LISTMAP 


NOPUBLICS. 
(default: x) 


The NLIST command is the opposite of the LIST command. It suppresses the 
listing of the elements specified. The elements can be tumed back on with the LIST 
command. 


Example 


NLIST O * Do not produce an object module. 
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Symbols 


# continuation character 11-43, 11-53 
$ 2-11 

% 2-11 

() 14-2 

© 2-9, 6-9, 11-17, 14-2 

+ 14-2 

+ (structured control directive code) 8-14 
, 14-2 

; 14-2 . 

<> (macto notation) 7-2 

= (exists) 7-2 

7? 2-7 

77 local labels 8-4 

?27INITDATA 11-31 

@ 2-11 

\@ 2-7 


A 


A2-AS relative addressing 4-18 
accessing dynamically allocated areas 4-22 
accessing statically allocated areas 4-20 
advantages 4-18 
ABSOLUTE command 11-6 
Absolute expressions 4-19 
Absolute symbols 5-8 
Address modes 4-8, 4-11 
68000/08/10 4-2 
68020/30/40 4-2 
absolute long 4-6 
absolute short 4-5 
address register direct 4-3 
address register indirect with displacement 
4-19 
CPU32 4-2 
data register direct 4-3 
floating-point 4-8 
immediate 4-8 
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memory indirect post-indexed 44 
memory indirect pre-indexed 4-5 
program counter memory indirect 
post-indexed 4-7 
pre-indexed 4-7 
program counter relative 4-3 
program counter with base 
displacement and index 4-6 
program counter with displacement 4-6 
register direct 4-3 
register indirect 4-3 
8-bit displacement and index 4-4 
base displacement and index 44 
displacement 4-4 
postincrement 4-3 
predecrement 4-4 
syntax 4-9 
user contro! 4-17 
Addressing modes 
(see Address modes) 
ALIAS command 11-8 
ALIGN command 11-10, 11-12 
ALIGN directive 6-3 
ALIGNMOD command 11-12 - 
ASCII code A-1 


ASM68K support 


name demangling F-2 
name mangling F-2 
Assembler 
absolute expressions 4-19 | 
addressing modes 3-1,4-1 - 
asmb_sym assembler symbol files 5-4, 10-5 
assembly-time relative addressing 2-5 
attributes 
common vs. noncommon 5-2 
section alignment 5-3. 
section type 5-3 
short vs. long 5-2 
character set 2-6 
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constants 2-10 
character 2-12 
floating-point 2-11 
integer 2-10 
cross-reference table format 9-3 
data record G-3 
directive statement 
format 2-1 
directives 6-1, 7-9, 8-5 
error messages B-1 
errors B-1 
floating-point 2-11, 3-18 
header record G-2 
HP 64000 files 5-4, 10-5 
instructions 3-1, 4-1 
link_sym linker symbol files 5-4, 10-5 
listing, sample program 9-4 
location counter 2-9 
macro directives 7-9 
messages B-1 
module record G-1 
object module 9-7 
operation 9-1 
program counter 2-9 
record count record G-4 
relative addressing 4-18 
relocatable expressions 4-19 
reserved symbo]s 2-8 
NARG 2-8 
section attributes 
assigning 5-6 
section types 5-5 
statements 2-1 
comment 2-4 
comment field 2-2 
examples 2-2 
label field 2-1 
operand field 2-2 
operation field 2-2 
structure contral directives 8-5 
symbol record G-2 
symbolic addressing 2-5 


Index-2 


Index 


symbols 2-7 
invalid 2-7 
relocatable versus absolute 5-8 
valid 2-7 
syntax 2-6 
terminator record G-5 
Assembler C++ output file F-5 
Assembler directives 
(see Directives) 
Assembler relocation flags 9-2 


B 


Base address 11-13 
BASE command 11-13 
Branch instruction labels 
local (77) 8-4 
BREAK command 8-6 


Cc 


C command line flag H-2 
c command line flag H-4 
CASE command 11-14 
Character constants 2-12 
Character set 

assembler 2-6 
CHIP command 11-15 
CHIP directive 6-4 
CLEAR command 14-6 
Code 

structured control directive (+) 8-14 
COMLINE directive 6-6 
Command line flags 


linker H-2 
Command position dependencies, linker 11-2 
Commands, librarian 
(see Librarian commands) 
Comment (*) command 11-17 
COMMON command 11-18 
COMMON directive 6-7 
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Constants 

(see Assembler constants) 
Continuation character (#) 11-43, 11-53 
Conventions, notational vii 
CPAGE command 11-20 
Cross-reference option 9-3 


D 


D command line flag H-2 
d command line flag H-4 
Data record G-3 
DC directive 6-9 
DCB directive 6-12 
DEBUG_SYMBOLS command 11-22 
Demangling F-1 
Directives 6-1 
Directives, assembler 
ALIGN 6-3 
CHIP 6-4 
COMLINE 6-6 
COMMON 6-7 
DC 6-9 
DCB 6-12 
DS 6-13 
ELSEC 6-14 
END 6-15 
ENDC 6-17 
ENDR 6-18 
EQU 6-19 
FAIL 6-20 
FEQU 6-22 
FOPT 6-23 
FORMAT 6-24 
IDNT 6-25 
IFC 6-26 
IFDEF 6-28 
IFEQ 6-29 
IFGE 6-31 
IFGT 6-32 
IFLE 6-33 
IFLT 6-34 
IFNC 6-35 
IFNDEF 6-37 
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IFNE 6-38 
INCLUDE 6-39 
IRP 6-40 
IRPC 6-42 
LIST 6-43 
LLEN 6-44 
MASK2 6-45 
NAME 6-46 
NOFORMAT 6-24 
NOLIST 6-43 
NOOBJ 6-47 
NOPAGE 6-58 
OFFSET 6-48 
OPT 6-50 
ORG 6-57 
PAGE 6-58 
PLEN 6-59 
REG 6-60 
REPT 6-61 
RESTORE 6-62 
SAVE 6-63 
SECT 6-64 
SECTION 6-64 
SET 6-66 
SPC 6-67 
TIL 6-68 
XCOM 6-69 
XDEF 6-70 
XREF 6-71 

Directives, macros 
ENDM 7-6 


Directives, structured control 
BREAK 8-6 
FOR...ENDF 8-7 
IF...THEN...ELSE...ENDI 8-9 
NEXT 8-11 
REPEAT...UNTIL 8-12 
WHILE...ENDW 8-13 
Disabling command line flags H-1, H-3 
Documentation, description v 
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index 


en 


DS directive 6-13 


E 


EBCDIC code A-1 
Effective address 4-19 
Effective address syntax 4-9 
ELSE directive 

structured syntax 8-9 
ELSEC directive 6-14 
Enabling command line flags H-1, H-3 
END command 11-23, 14-10 
END directive 6-15 
ENDC directive 6-17 
ENDI directive 8-9 
ENDM directive 7-6 
ENDR directive 6-18 
ENDW directive 8-13 
EQU directive 6-19 
ERROR command 11-24 
Esror messages 

assembler B-1 
Errors 

assembler B-1 

librarian D-1 

linker C-1 
exists (==) 7-2 
EXIT command 11-25 
Expression 2-14 

complex 5-9 

relocatable 5-8 
EXTERN command 11-26 
External symbols 5-7 


F 


-f linker command line option H-3 
FAIL directive 6-20 
Features 
librarian 13-1 
Features, ASM68K 1-2 
FEQU directive 6-22 
FLAGS command line option H-1 
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addressing modes 4-8 

constants 2-11 

coprocessor 3-18 

double precision 6-10 

single precision 6-10 
FOPT directive 6-23 
FOR...ENDF loop 8-7 
FORMAT command 11-27 
FORMAT directive 6-24 
Formats 

data record G-3 

Motorola S-record G-1 
Function 

librarian 13-1 
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I command line flag H-2 
i command line flag H-4 
IDNT directive 6-25 
IF directive 
structured syntax 8-9 
IF... THEN...ELSE...ENDI 
conditional execution 8-9 
IFC directive 6-26 
IFDEF directive 6-28 
IFEQ directive 6-29 
IFGE directive 6-31 
IFGT directive 6-32 
IFLE directive 6-33 
IFLT directive 6-34 
IFNC directive 6-35 
IFNDEF directive 6-37 
IFNE directive 6-38 
INCLUDE command 11-28 
INCLUDE directive 6-39 
Incremental linking 10-1, 10-7 
INDEX command 11-29 
INDEX linker command 4-19 
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INITDATA command 11-31 

Instruction operands 3-15 

Instruction types, variants 3-14 

Instructions 3-1, 3-4 

Integer constants 2-10 

Invocation methods, librarian 
command file 13-3 
command line 13-3 
jnteractive 13-3 

IRP directive 640 

IRPC directive 6-42 
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LIB68K support 
demangled name F-20 
mangled name F-20 

Librarian 
alphabetical listing of commands 14-1 
blanks 14-3 
command characters 

asterisk 14-2 
comma 14-2 
parentheses 14-2 
plus 14-2 
semicolon 14-2 
command file comments 14-3 
command syntax 14-2 
commands 14-1 
ADDLIB 14-4 
ADDMOD 14-5 
CLEAR 14-6 
CREATE 14-7 
DELETE 14-8 
DIRECTORY 14-9 
END 14-10 
EXTRACT 14-11 
FULLDIR 14-12 
HELP 14-14 
OPEN 14-15 
QUIT 14-10 
REPLACE 14-16 
SAVE 14-17 
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message severity levels D-1 
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overview 13-1 
return codes 13-6 
special characters 14-2 
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comma 14-2 
left parenthesis 14-2 
plus 14-2 
right parenthesis 14-2 
semicolon 14-2 
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absolute output file 12-9 
alphabetical listing of commands 11-4 
command file 12-4 
command position dependencies 11-2 
command syntax 11-1 
commands 

ABSOLUTE 11-6 

ALIAS 11-8 

ALIGN 11-10, 11-12 

ALIGNMOD 11-12 

BASE 11-13 

CASE 11-14 

CHIP 11-15 

Comment (*) 11-17 

COMMON 11-18 

CPAGE 11-20 

DEBUG_SYMBOLS 11-22 

END 11-23 

ERROR 11-24 

EXIT 11-25 

EXTERN 11-26 


Index-5 


FORMAT 11-27 
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INDEX 4-19, 4-22, 11-29 
INITDATA 11-31 
LISTABS 11-32 
LISTMAP 11-33 
LOAD 11-35 
LOAD_SYMBOLS 11-37 
LOWERCASE 11-38 
MERGE 11-39 
NAME 11-41 
NODEBUG_SYMBOLS 11-22 
NOERROR 11-24 
NOPAGE 11-44 
ORDER 11-42 
PAGE 11-44 
PUBLIC 11-46 
RESADD 11-48 
RESMEM 11-49 
SECT 11-50 
SECTSIZE 11-51 
SORDER 11-52 
START 11-54 
UPPERCASE 11-55 
WARN 11-56 
completion status message 12-3 
cross-reference table 12-3 
errors C-1 
features 10-2 
incremental linking 10-1, 10-7 
listing, sample 12-1 
map file 12-5 
memory space assignment 10-5 
message severity levels C-1 
messages C-1 
operation 10-1, 12-1 
public symbol table 12-3 
relocation types 10-6 
sample assembly listings used 12-10 
sections 
absolute 10-2 
common 10-3 
long 104 
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noncommon 10-3 
relocatable 10-3 
section alignment 10-5 
section type 10-4 
short 10-4 
start address 12-3 
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command line flags H-4 
unresolved externals 12-2 
VMS 
command line flags H-2 
Linking 5-7 
LIST command H-6 
LIST directive 6-43 
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LISTMAP command 11-33 
LLEN directive 6-44 ; 
LNK68K support 
symbol name size F-9 
LOAD command 11-35 
LOAD_SYMBOLS command 11-37 
LOCAL directive 7-7 
Local labels (77) 8-4 
Location counter 2-9 
LOWERCASE command 11-38 
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Macro body 7-9 
Macro call 7-2 
MACRO directive 7-9 
Macro directives 

(see Directives) 
Macro parameter count 7-4 
Macro statement format 2-3 
Macro terminator 7-6 
Macros 

directives 7-9 

ENDM 7-6 

LOCAL 7-7 

MACRO 7-9 

MEXIT 7-11 

parameter delimiter (<>) 7-2 

parameter exists (==) 7-2 
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MASK2 directive 6-45 
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MERGE command 11-39 
Message severity levels 
librarian D-1 
linker C-1 
Messages 
assembler B-1 
linker C-1 
MEXIT directive 7-11 
Module 13-1 
Module record G-1 
Motorola S-record format G-1 


N 


NAME command 11-41 

Name demangling F-1 

NAME directive 6-46 

NARG reserved symbol 2-8, 7-4 
NARG symbol 9-3 

NEXT command 8-11 

NLIST command H-9 
NODEBUG_SYMBOLS command 11-22 
NOERROR command 11-24 
NOFORMAT directive 6-24 
NOLIST directive 6-43 

NOOB] directive 6-47 
NOPAGE command 11-44 
NOPAGE directive 6-58 
Notational conventions vii 
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O command line flag H-2 
o command line flag H-4 
O opcode error 8-14 
OFFSET directive 6-48 
opcode error (O) 8-14 
Operand syntax 4-11 
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Operators 2-15 
OPT directive 6-50 
ORDER command 11-42 
ORG directive 6-57 
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P command line flag H-2 
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PAGE command 11-44 
PAGE directive 6-58 
Parameter count, macto 7-4 
PLEN directive 6-59 
Program counter 2-9 
Program sections 5-1 
Pseudo-Ops 

(see Directives) 
PUBLIC command 11-46 
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QUIT command 14-10 
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REG directive 6-60 - 
Registers 3-15 

Relative addressing 4-18 
Relocatable expressions 4-19, 5-8 
Relocatable symbols 5-8 
Relocation 5-1 

Relocation flags, assembler 9-2 
Relocation types 10-6 
REPEAT directive 8-12 
REPEAT...UNTIL loop 8-12 
REPT directive 6-61 

RESADD command 11-48 
Reserved symbols 2-8 
RESMEM command 11-49 
RESTORE directive 6-62 
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S command line flag H-2 
$ command line flag H-4 
SAVE command 14-17 
SAVE directive 6-63 
SECT command 11-50 
SECT directive 6-64 
Section alignment 10-5 
SECTION directive 6-64 
Section type 10-4 
Sections 5-1 

absolute 10-2 

common 10-3 

long 10-4 

noncommon 10-3 

relocatable 10-3 

short 10-4 
SECTSIZE command 11-51 
SET directive 6-66 
-SIZEOF. operator 2-17 
SORDER command 11-52 
SPC directive 6-67 
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S-Record format G-1 
START command 11-54 
-STARTOF. operator 2-16 
Structured control directive 

code (+) 8-14 
Structured control expressions 8-1 
Structured control statements 8-1 
Structured directives, nesting 8-14 
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Symbolic addressing 2-5 
Symbols 

absolute 5-8 
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T command line flag H-2 
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TTL directive 6-68 
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U undefined label error 8-14 
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d H-4 
i H-4 
o H-4 
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s H4 
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WARN command 11-56 
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Reader’s Response 


Please complete and retum the following Reader's Response form to help 
us improve our documentation. Your comments and suggestions are 


always appreciated. 

Product Name Manua! Date/Version 

Your Name Title 

Company Address 

Phone Number 

What is your level of programming experience? In this language? 
Advanced Advanced 
Intermediate Intermediate 
Beginner Beginner 


Circle the number which bast expresses your rating of the information In this manual (5 is the highest rating): 


Complete? 1 2 3 4 §5 Easy to understand? 1 2 3 '4 5 
Accurate? 1 2 3 4 65 Helpful examples? 1 2 3 4 #5 
Wellorganized? 1 2 3 4 § Helpful procedures? 1 2 3.4.4 5 
EasytoFind? 1 2 3 4 § At an appropriate level? =i 2 3 4 5 
EasytoRead? 1 2 3 4 § Overall rating? 1 2 3 4 5 


3.) Which programming language do you use? 


4.) Does the manual provide all the necessary information? If not, what Is missing? 


5.) Are more examptes needed? If so, where? 


8.) Did you have any difficulty understanding descriptions or wording? If so, where? 


7.) Which sections of this manual are the most important? The most helpful? 


8.) What are the best features of this manual? 


9.) What are the areas In this manual that need improvement? 


10.) Did you find any errors In this manual? (Specify section and page number.) 
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Software Performance Report Instructions 


( #00 If problems or errors are encountered when using Microtec Research’s software products (includ- 
Pgs ing documentation), a Software Performance Report (SPR) should be completed and returned to: 


Microtec Research 
Software Performance Reports 
2350 Mission Coliege Boulevard 
Santa Clara, CA 95054 


Any comments or suggestions you may have should also be included. All SPRs are directed to our 
Technical Support Department for analysis and response. 


When completing the top section of the SPR, enter the following: 


1. 


we OnNAWA WH 


Product name and Version number as it appears on the media label or the banner that 
appears on the screen when the product is invoked. 


. Serial Number as it appears on the media label. 


Name of the person (Customer) that Microtec Research can contact. 
Name of the company that the software was Purchased From. 


. Company Name and a shipping Address. 

. Phone Number and/or FAX Number of contact name. 

. Host (machine where the Microtec Research product is run). 
. Host Operating System and Version Number. 

. Report Type showing the type of problem reported. 


10. Customer Impact indicating the severity of the problem. 


The following guidelines should be followed when completing the bottom section of the SPR: 


| é 
| 7. 


1. 


Give as complete a description as possible of the problem, error, or suggestion, 
including the exact wording of any error messages. 


. If possible, isolate the problem by providing a small-example. 
. If the error example is longer than one page of source code, send all information ona 


tape or floppy disk. 
Carefully label any media you send and indicate whether you want it returned to you. 


Include command files, listings, load maps, include files, data files, and all other 
relevant material with the SPR. 


If applicable, send sample input and output listings. 
If the output is from a compiler, send a mixed (source/assembly code) listing. 


If the information on the SPR is complete and concise, it will help us give you accurate and timely 
service to any software problem. 


Sottware Performance Report 


Product: Customer: 


Company Name/Address 


Version: 
Serial Number: 


Purchased From: 


Host: [ ] Apollo { } HP [ }PC [ ] Other 
{ ] Sun-3 [ ]Sun-4/SPARC [ ] VMS 
Operating System Version 
Report Type: Customer Impact: 
{ ] ProblenvError [ ] Heavy 
[ } Documentation [ ] Moderate 
[ ] Feature Request { ] Minor 
[ ] Other 


Problem Description (Attach additional pages if needed): 


Problem Recreation (Commands or lines of code used to duplicate problem): 


Workaround (Attach additional pages if needed): 


VA 


Microtec 
Research Inc. 


2350 Mission College Blvd. 


Santa Clara, CA 95054 
Tel. 408.980.1300 

Toll Free 800.950.5554 
FAX 408.982.8266 


